@twin.org/move-to-json 0.0.2-next.9 → 0.0.3-next.10

package/README.md

@@ -1,387 +1,21 @@
 # TWIN Move to JSON
 
-Tool to convert Move source files to JSON with network-specific deployment support.
-
-## Prerequisites
-
-### IOTA CLI Installation
-
-Before using this tool, you need to install the IOTA CLI. The simplest way is using Homebrew:
-
-```bash
-# Install IOTA CLI using Homebrew (macOS/Linux/WSL)
-brew install iotaledger/tap/iota
-```
-
-**Alternative installation methods:**
-
-For other platforms or installation from source, see the [official IOTA installation guide](https://docs.iota.org/developer/getting-started/install-iota).
-
-**Verify installation:**
-
-```bash
-iota --version
-```
+This app provides a command line workflow for compiling Move contracts and producing deployment-ready JSON for IOTA networks. It is intended for development teams that want predictable build and deployment inputs across test and production environments.
 
 ## Installation
 
 ```shell
-npm install -g @twin.org/move-to-json
-```
-
-## Quick Start
-
-```bash
-# Build contracts for mainnet using environment variables (recommended)
-npx move-to-json build "src/**/*.move" --load-env configs/mainnet.env --output smart-contract-deployments.json
-
-# Deploy to mainnet using environment variables (recommended)
-npx move-to-json deploy --load-env configs/mainnet.env --contracts smart-contract-deployments.json
-```
-
-## Environment Setup for Production Deployments
-
-### Required Environment Variables
-
-For production deployments, you need to set up environment variables containing your deployment credentials. The tool uses network-specific configuration files located in the `configs/` directory.
-
-#### 1. Create Environment Files
-
-Copy the environment templates for each network you plan to use:
-
-```bash
-# Copy environment templates for each network
-cp configs/testnet.env.example configs/testnet.env
-cp configs/devnet.env.example configs/devnet.env
-cp configs/mainnet.env.example configs/mainnet.env
-```
-
-**Note:** Only copy the environment files for the networks you actually plan to deploy to. For development, you typically only need `testnet.env` and `devnet.env`.
-
-#### 2. Generate Deployment Mnemonics
-
-Use the wallet CLI to generate secure mnemonics and then manually update the appropriate network configuration files with the generated mnemonic.
-
-### Environment Variable Reference
-
-Each network has its own configuration file in the `configs/` directory with the required deployment mnemonic:
-
-| Network | File                  | Required Variable   |
-| ------- | --------------------- | ------------------- |
-| Testnet | `configs/testnet.env` | `DEPLOYER_MNEMONIC` |
-| Devnet  | `configs/devnet.env`  | `DEPLOYER_MNEMONIC` |
-| Mainnet | `configs/mainnet.env` | `DEPLOYER_MNEMONIC` |
-
-### Security Best Practices
-
-#### Local Development
-
-- Store credentials in `configs/*.env` files (never commit to git - only commit `.example` files)
-- Use test mnemonics with faucet funds for testnet/devnet
-- Use dedicated deployment wallets separate from personal wallets
-
-#### CI/CD and Production
-
-- Store credentials in GitHub Secrets or your CI/CD secrets manager
-- Use hardware wallets or HSM for mainnet deployment keys
-- Implement approval workflows for mainnet deployments
-- Monitor wallet balances and deployment costs
-
-### Generating Credentials
-
-#### 1. Generate Mnemonic and Seed
-
-```bash
-# Generate a new 24-word mnemonic and save to wallet.env
-npx "@twin.org/wallet-cli" mnemonic --env wallet.env
-```
-
-#### 2. Generate Addresses from Seed
-
-```bash
-# Generate 5 addresses and save to address.env
-npx "@twin.org/wallet-cli" address --load-env wallet.env --seed '!SEED' --count 5 --env address.env
-```
-
-## Commands
-
-### build
-
-Compile Move contracts for a specific network:
-
-```bash
-# Using environment variables (recommended)
-npx move-to-json build "src/**/*.move" --load-env configs/<network>.env [--output <file>]
-
-# Using explicit network flag
-npx move-to-json build "src/**/*.move" --network <network> [--output <file>]
-
-# If installed globally
-move-to-json build "src/**/*.move" --load-env configs/<network>.env [--output <file>]
-```
-
-**Options:**
-
-- `--network <network>` - Target network (testnet/devnet/mainnet) **[Optional if using --load-env]**
-- `--load-env <file>` - Load environment variables from file (must contain NETWORK variable)
-- `--output <file>` - Output JSON file (default: smart-contract-deployments.json)
-
-**What it does:**
-
-1. Reads network from `--network` flag or `NETWORK` environment variable
-2. Validates environment variables for the target network
-3. Cleans build artifacts and Move.lock files
-4. Compiles contracts using unified Move.toml (same bytecode for all networks)
-5. Generates network-aware JSON with package IDs and base64 modules
-
-**Key Changes:**
-
-- **Unified Move.toml**: Uses single Move.toml file with `framework/testnet` for consistent builds
-- **Network-agnostic compilation**: Same bytecode works across all networks
-- **Environment-aware**: Network targeting handled by IOTA CLI environments, not Move.toml
-
-**Example:**
-
-```bash
-# Build for testnet using environment variables (recommended)
-npx move-to-json build "tests/fixtures/sources/**/*.move" --load-env configs/testnet.env --output tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-
-# Build for mainnet using environment variables (recommended)
-npx move-to-json build "src/contracts/**/*.move" --load-env configs/mainnet.env --output smart-contract-deployments.json
-
-# Alternative: using explicit network flag
-npx move-to-json build "tests/fixtures/sources/**/*.move" --network testnet --output tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-```
-
-### deploy
-
-Deploy compiled contracts to the specified network:
-
-```bash
-# Using environment variables (recommended)
-npx move-to-json deploy --load-env configs/<network>.env [--contracts <file>] [options]
-
-# Using explicit network flag
-npx move-to-json deploy --network <network> [--load-env configs/<network>.env] [options]
-
-# If installed globally
-move-to-json deploy --load-env configs/<network>.env [--contracts <file>] [options]
+npm install -D @twin.org/move-to-json
 ```
 
-**Options:**
+## Usage
 
-- `--network <network>` - Network identifier (testnet/devnet/mainnet) **[Optional if using --load-env]**
-- `--load-env <file>` - Load environment variables from file (must contain NETWORK variable)
-- `--contracts <file>` - Compiled modules JSON file (default: smart-contract-deployments.json)
-- `--dry-run` - Simulate deployment without executing
-- `--force` - Force redeployment of existing packages
+Usage of the CLI is shown in the examples [docs/usage.md](docs/usage.md)
 
-**What it does:**
+## Reference
 
-1. Switches IOTA CLI to target network environment
-2. Loads environment variables from the file specified via `--load-env` flag
-3. Validates deployment credentials are available
-4. Checks wallet balance against gas requirements
-5. Loads compiled contracts from JSON
-6. Deploys using IOTA CLI with active network environment
-7. Extracts and saves both Package ID and UpgradeCap ID
-8. Updates JSON with deployed package information
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
 
-**Key Changes:**
+## Changelog
 
-- **Environment switching**: Automatically switches IOTA CLI to target network
-- **Network targeting**: Uses IOTA CLI environments instead of Move.toml configuration
-- **Consistent deployment**: Same compiled bytecode deployed to all networks
-- **UpgradeCap tracking**: Captures and stores UpgradeCap object ID for future package upgrades
-
-**Prerequisites:**
-Ensure IOTA CLI environments are configured:
-
-```bash
-# Check available environments
-iota client envs
-
-# Configure networks if missing
-iota client new-env --alias testnet --rpc https://fullnode.testnet.iota.cafe:443
-iota client new-env --alias mainnet --rpc https://api.mainnet.iota.cafe
-iota client new-env --alias devnet --rpc https://api.devnet.iota.cafe
-```
-
-**Example:**
-
-```bash
-# Deploy to testnet using environment variables (recommended)
-npx move-to-json deploy --load-env configs/testnet.env --contracts tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-
-# Deploy to mainnet using environment variables (recommended)
-npx move-to-json deploy --load-env configs/mainnet.env --contracts tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-
-# Dry run (simulation)
-npx move-to-json deploy --load-env configs/testnet.env --contracts tests/fixtures/smart-contract-deployments/smart-contract-deployments.json --dry-run
-```
-
-**Output:**
-The deployment saves both Package ID and UpgradeCap ID:
-
-```json
-{
-  "testnet": {
-    "packageId": "0x...",
-    "package": "base64data...",
-    "deployedPackageId": "0x239ad3ea39f0910a4dc4c98161bcde948fb5ed0d7d7ae6d9a593239c43af748e",
-    "upgradeCap": "0xfd6269c28e3931e41aa9d9e08ffabb8162cf1fd0baaef14094b4442e6c743edf"
-  }
-}
-```
-
-**Important Note on UpgradeCap:**
-The UpgradeCap ID is crucial for package upgrades. Keep this secure - it's required to upgrade your deployed packages in the future.
-
-## Unified Move.toml Approach
-
-The tool now uses a **unified Move.toml approach** that eliminates the need for network-specific Move.toml files. This provides better consistency and reduces complexity.
-
-### Single Move.toml Configuration
-
-Instead of multiple `Move.toml.{network}` files, use a single `Move.toml` file:
-
-```toml
-[package]
-name = "my_contract"
-version = "0.0.1"
-edition = "2024.beta"
-
-[dependencies]
-Iota = {
-    git = "https://github.com/iotaledger/iota.git",
-    subdir = "crates/iota-framework/packages/iota-framework",
-    rev = "framework/testnet"
-}
-
-[addresses]
-my_contract = "0x0"
-
-[dev-dependencies]
-# Optional: Override dependencies for testing
-# Iota = { git = "https://github.com/iotaledger/iota.git", subdir = "crates/iota-framework/packages/iota-framework", rev = "framework/devnet", override = true }
-
-[dev-addresses]
-# Optional: Override addresses for development
-# my_contract = "0x1234"
-```
-
-### Framework Version Strategy
-
-- **Development/Testing**: Use `framework/testnet` for all networks
-- **Production**: Same `framework/testnet` works for mainnet deployment
-- **Consistency**: Same bytecode compiles for all target networks
-
-### Network Targeting
-
-Network targeting is handled through **IOTA CLI environments**, not Move.toml:
-
-```bash
-# Build once - same bytecode for all networks
-iota move build
-
-# Deploy to different networks by switching environments
-iota client switch --env testnet && iota client publish
-iota client switch --env mainnet && iota client publish
-```
-
-### Benefits
-
-- ✅ **Consistent builds** across all networks
-- ✅ **Reduced complexity** - no file copying
-- ✅ **Industry standard** approach
-- ✅ **Better maintainability** - single source of truth
-- ✅ **Eliminated build conflicts** between networks
-
-## Package Upgrades and UpgradeCap Management
-
-When you deploy a Move package on IOTA, the network creates an **UpgradeCap** (Upgrade Capability) object that controls the ability to upgrade that package. This tool automatically captures and stores the UpgradeCap ID for future use.
-
-### What is an UpgradeCap?
-
-The UpgradeCap is a special object that:
-
-- **Controls package upgrades**: Only the holder can upgrade the package
-- **Is created once**: Generated during initial package deployment
-- **Must be preserved**: Lost UpgradeCap = no future upgrades possible
-- **Is network-specific**: Each network deployment gets its own UpgradeCap
-
-### UpgradeCap Storage
-
-The tool stores UpgradeCap IDs in the smart-contract-deployments.json file:
-
-```json
-{
-  "testnet": {
-    "packageId": "0xabc123...",
-    "package": "base64data...",
-    "deployedPackageId": "0x239ad3ea39f0910a4dc4c98161bcde948fb5ed0d7d7ae6d9a593239c43af748e",
-    "upgradeCap": "0xfd6269c28e3931e41aa9d9e08ffabb8162cf1fd0baaef14094b4442e6c743edf"
-  }
-}
-```
-
-### Using UpgradeCap for Package Upgrades
-
-To upgrade a deployed package, you'll need the UpgradeCap ID:
-
-```bash
-# Example upgrade command (using IOTA CLI)
-iota client call --package 0x2 --module package --function upgrade \
-  --args 0xfd6269c28e3931e41aa9d9e08ffabb8162cf1fd0baaef14094b4442e6c743edf \
-  --gas-budget 50000000
-```
-
-## Known Issues
-
-### Windows
-
-#### Long Path Limitation Error
-
-**Error Symptoms:**
-
-- Build commands fail with `Failed to reset to latest Git state 'mainnet'`
-- Tests timeout during Move compilation
-- Git dependency resolution failures
-
-**Root Cause:**
-Windows has a default file path length limitation of 260 characters. The IOTA framework repository contains files with very long paths (especially in test directories) that exceed this limit, causing Git operations to fail during dependency resolution.
-
-**Solution:**
-Enable long path support in both Git and Windows:
-
-1. **Enable Git Long Paths:**
-
-   ```bash
-   git config --global core.longpaths true
-   ```
-
-2. **Enable Windows Long Path Support (requires Administrator privileges):**
-
-   ```powershell
-   # Run PowerShell as Administrator
-   Set-ItemProperty -Path 'HKLM:SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
-   ```
-
-3. **Restart your computer** for Windows registry changes to take effect.
-
-**Verification:**
-After applying the fix, you should see successful Git dependency updates:
-
-```bash
-UPDATING GIT DEPENDENCY https://github.com/iotaledger/iota.git
-INCLUDING DEPENDENCY Iota
-INCLUDING DEPENDENCY MoveStdlib
-BUILDING nft
-```
-
-**Alternative Workaround:**
-If you cannot enable long path support system-wide, you can use the `--skip-fetch-latest-git-deps` flag as a workaround, though this will use cached dependencies instead of the latest versions:
-
-```bash
-iota move build --skip-fetch-latest-git-deps
-```
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)

package/bin/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { CLI } from '../dist/esm/index.mjs';
+import { CLI } from '../dist/es/index.js';
 
 const cli = new CLI();
 const result = await cli.run(process.argv);

package/dist/es/cli.js

@@ -0,0 +1,39 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLIBase } from "@twin.org/cli-core";
+import { buildCommandBuild } from "./commands/build.js";
+import { buildCommandDeploy } from "./commands/deploy.js";
+/**
+ * The main entry point for the Move to JSON CLI.
+ */
+export class CLI extends CLIBase {
+    /**
+     * Run the app.
+     * @param argv The process arguments.
+     * @param localesDirectory The directory for the locales, default to relative to the script.
+     * @param options Additional options.
+     * @param options.overrideOutputWidth Override the output width.
+     * @returns The exit code.
+     */
+    async run(argv, localesDirectory, options) {
+        return this.execute({
+            title: "TWIN Move to JSON",
+            appName: "move-to-json",
+            version: "0.0.3-next.10", // x-release-please-version
+            icon: "⚙️ ",
+            supportsEnvFiles: true,
+            overrideOutputWidth: options?.overrideOutputWidth
+        }, localesDirectory ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "../locales"), argv);
+    }
+    /**
+     * Configure any options or actions at the root program level.
+     * @param program The root program command.
+     */
+    configureRoot(program) {
+        buildCommandBuild(program);
+        buildCommandDeploy(program);
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/es/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,OAAO,GAAI,SAAQ,OAAO;IAC/B;;;;;;;OAOG;IACI,KAAK,CAAC,GAAG,CACf,IAAc,EACd,gBAAyB,EACzB,OAEC;QAED,OAAO,IAAI,CAAC,OAAO,CAClB;YACC,KAAK,EAAE,mBAAmB;YAC1B,OAAO,EAAE,cAAc;YACvB,OAAO,EAAE,eAAe,EAAE,2BAA2B;YACrD,IAAI,EAAE,KAAK;YACX,gBAAgB,EAAE,IAAI;YACtB,mBAAmB,EAAE,OAAO,EAAE,mBAAmB;SACjD,EACD,gBAAgB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,EACzF,IAAI,CACJ,CAAC;IACH,CAAC;IAED;;;OAGG;IACO,aAAa,CAAC,OAAgB;QACvC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3B,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { CLIBase } from \"@twin.org/cli-core\";\nimport type { Command } from \"commander\";\nimport { buildCommandBuild } from \"./commands/build.js\";\nimport { buildCommandDeploy } from \"./commands/deploy.js\";\n\n/**\n * The main entry point for the Move to JSON CLI.\n */\nexport class CLI extends CLIBase {\n\t/**\n\t * Run the app.\n\t * @param argv The process arguments.\n\t * @param localesDirectory The directory for the locales, default to relative to the script.\n\t * @param options Additional options.\n\t * @param options.overrideOutputWidth Override the output width.\n\t * @returns The exit code.\n\t */\n\tpublic async run(\n\t\targv: string[],\n\t\tlocalesDirectory?: string,\n\t\toptions?: {\n\t\t\toverrideOutputWidth?: number;\n\t\t}\n\t): Promise<number> {\n\t\treturn this.execute(\n\t\t\t{\n\t\t\t\ttitle: \"TWIN Move to JSON\",\n\t\t\t\tappName: \"move-to-json\",\n\t\t\t\tversion: \"0.0.3-next.10\", // x-release-please-version\n\t\t\t\ticon: \"⚙️ \",\n\t\t\t\tsupportsEnvFiles: true,\n\t\t\t\toverrideOutputWidth: options?.overrideOutputWidth\n\t\t\t},\n\t\t\tlocalesDirectory ?? path.join(path.dirname(fileURLToPath(import.meta.url)), \"../locales\"),\n\t\t\targv\n\t\t);\n\t}\n\n\t/**\n\t * Configure any options or actions at the root program level.\n\t * @param program The root program command.\n\t */\n\tprotected configureRoot(program: Command): void {\n\t\tbuildCommandBuild(program);\n\t\tbuildCommandDeploy(program);\n\t}\n}\n"]}

package/dist/es/commands/build.js

@@ -0,0 +1,220 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { promises as fsPromises } from "node:fs";
+import path from "node:path";
+import { CLIDisplay, CLIParam, CLIUtils } from "@twin.org/cli-core";
+import { Converter, GeneralError, Guards, I18n, Is, StringHelper } from "@twin.org/core";
+import { Sha3 } from "@twin.org/crypto";
+import { NetworkTypes } from "@twin.org/dlt-iota";
+import FastGlob from "fast-glob";
+import { verifyIotaSDK } from "../utils/iotaUtils.js";
+import { searchDirectoryForMoveToml } from "../utils/moveToJsonUtils.js";
+/**
+ * Build the build command to be consumed by the CLI.
+ * @param program The command to build on.
+ */
+export function buildCommandBuild(program) {
+    program
+        .command("build")
+        .description(I18n.formatMessage("commands.build.description"))
+        .argument("<inputGlob>", I18n.formatMessage("commands.build.options.inputGlob.description"))
+        .option(I18n.formatMessage("commands.build.options.network.param"), I18n.formatMessage("commands.build.options.network.description"), "!NETWORK")
+        .option(I18n.formatMessage("commands.build.options.output.param"), I18n.formatMessage("commands.build.options.output.description"), "smart-contract-deployments.json")
+        .action(actionCommandBuild);
+}
+/**
+ * Action for the build command.
+ * @param inputGlob A glob pattern that matches one or more Move files
+ * @param opts Additional options.
+ * @param opts.network Target network (testnet/devnet/mainnet).
+ * @param opts.output Where we store the final compiled modules.
+ */
+export async function actionCommandBuild(inputGlob, opts) {
+    try {
+        const networkRaw = CLIParam.stringValue("network", opts.network);
+        const network = networkRaw;
+        Guards.arrayOneOf("commands", "network", network, Object.values(NetworkTypes));
+        // Verify the IOTA SDK before we do anything else
+        await verifyIotaSDK();
+        const { normalizedGlob, normalizedOutput, executionDir } = normalizePathsAndWorkingDir(inputGlob, opts.output ?? "smart-contract-deployments.json");
+        CLIDisplay.section(I18n.formatMessage("commands.build.section.buildingMoveContracts", {
+            network
+        }));
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.inputGlob"), inputGlob);
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.outputJson"), normalizedOutput);
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.network"), network);
+        CLIDisplay.break();
+        // Find matching .move files
+        CLIDisplay.task(I18n.formatMessage("commands.build.progress.searchingFiles"));
+        const matchedFiles = await FastGlob([normalizedGlob, "!**/build/**/*.move", "!**/dependencies/**/*.move"], {
+            cwd: executionDir,
+            absolute: true,
+            dot: true,
+            followSymbolicLinks: false,
+            caseSensitiveMatch: false, // Important for Windows
+            onlyFiles: true,
+            stats: false
+        });
+        if (matchedFiles.length === 0) {
+            CLIDisplay.value(I18n.formatMessage("commands.build.warnings.noMoveFilesFound", { inputGlob }), "", 2);
+        }
+        else if (matchedFiles.length > 1) {
+            throw new GeneralError("commands", "commands.build.multipleFilesNotSupported", {
+                fileCount: matchedFiles.length,
+                fileList: matchedFiles.map(f => path.basename(f)).join(", ")
+            });
+        }
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.matchedFilesCount"), matchedFiles.length.toString());
+        CLIDisplay.break();
+        // Prepare build environment
+        CLIDisplay.task(I18n.formatMessage("commands.build.progress.preparingBuildEnvironment"));
+        // Find all Move projects in the directory tree
+        const moveProjects = [];
+        await searchDirectoryForMoveToml(executionDir, moveProjects);
+        for (const projectRoot of moveProjects) {
+            CLIDisplay.value(I18n.formatMessage("commands.build.labels.preparedProject"), projectRoot, 1);
+        }
+        const existingJson = await CLIUtils.readJsonFile(normalizedOutput);
+        const finalJson = existingJson ?? {};
+        if (existingJson) {
+            CLIDisplay.value(I18n.formatMessage("commands.build.labels.mergingWithExistingJson"), normalizedOutput);
+        }
+        else {
+            CLIDisplay.value(I18n.formatMessage("commands.build.labels.noExistingJsonFound"), I18n.formatMessage("commands.build.labels.creatingNewJsonStructure"), 1);
+        }
+        CLIDisplay.break();
+        // Process the single Move file (validation ensures exactly 0 or 1 file)
+        if (matchedFiles.length === 1) {
+            const moveFile = matchedFiles[0];
+            CLIDisplay.task(I18n.formatMessage("commands.build.progress.processingMoveFile"), moveFile);
+            try {
+                const compiled = await processMoveFile(moveFile);
+                if (compiled) {
+                    const { contractName, packageId, packageBytecode } = compiled;
+                    const contractData = finalJson[network] ?? {
+                        packageId: "",
+                        packageBytecode: ""
+                    };
+                    // If the packageId changed that means the bytecode changed
+                    // since the packageId is a hash of the bytecode.
+                    if (packageId !== contractData.packageId) {
+                        contractData.packageId = packageId; // Update packageId to new value
+                        contractData.packageBytecode = packageBytecode; // Update bytecode
+                        // If deployedPackageId exists, it means this contract was previously deployed.
+                        // so we need to clear it to signal that a redeployment (upgrade) is needed.
+                        // but also capture it so that we can perform upgrades
+                        if (Is.stringValue(contractData.deployedPackageId)) {
+                            contractData.lastDeployedPackageId = contractData.deployedPackageId;
+                            // Clear deployedPackageId when bytecode changed, preserve upgrade metadata
+                            delete contractData.deployedPackageId; // Clear to signal upgrade needed
+                        }
+                        finalJson[network] = contractData;
+                        CLIDisplay.value(I18n.formatMessage("commands.build.labels.bytecodeChanged"), I18n.formatMessage("commands.build.labels.deployedPackageIdCleared"), 2);
+                    }
+                    else {
+                        CLIDisplay.value(I18n.formatMessage("commands.build.labels.bytecodeUnchanged"), I18n.formatMessage("commands.build.labels.deployedPackageIdPreserved"), 2);
+                    }
+                    CLIDisplay.value(I18n.formatMessage("commands.build.labels.updatedNetworkPackage", { network }), contractName, 2);
+                }
+            }
+            catch (err) {
+                throw new GeneralError("commands", "commands.build.contractProcessingFailed", { file: moveFile }, err);
+            }
+            CLIDisplay.break();
+        }
+        CLIDisplay.task(I18n.formatMessage("commands.build.progress.writingJsonFile"));
+        await CLIUtils.writeJsonFile(normalizedOutput, finalJson, false);
+        CLIDisplay.break();
+        CLIDisplay.done();
+    }
+    catch (err) {
+        CLIDisplay.error(err);
+        throw err;
+    }
+}
+/**
+ * Process a single Move file by compiling it, computing the packageId, and base64-encoding the .mv modules.
+ * @param moveFile The path to a single Move source file.
+ * @returns The compiled results or undefined if no modules found.
+ */
+async function processMoveFile(moveFile) {
+    // The contract name is based on the .move file's base name in kebab-case
+    const { name: baseName } = path.parse(moveFile);
+    const contractName = StringHelper.kebabCase(baseName);
+    // Find the "project root" (the directory containing Move.toml).
+    const projectRoot = getProjectRoot(moveFile);
+    CLIDisplay.value(I18n.formatMessage("commands.build.labels.contractName"), contractName, 1);
+    // Compile the contract
+    try {
+        const cliArgs = ["move", "build"];
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.compileCommand"), `iota ${cliArgs.join(" ")}`, 1);
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.workingDirectory"), projectRoot, 1);
+        await CLIUtils.runShellApp("iota", cliArgs, projectRoot);
+        CLIDisplay.value(I18n.formatMessage("commands.build.labels.compileResult"), I18n.formatMessage("commands.build.labels.buildCompleted"), 1);
+    }
+    catch (error) {
+        throw new GeneralError("commands", "commands.build.buildFailed", { file: moveFile }, error);
+    }
+    // Get the bytecode modules
+    const buildFolderName = StringHelper.snakeCase(baseName);
+    const bytecodeModulesPath = path.join(projectRoot, "build", buildFolderName, "bytecode_modules");
+    try {
+        await fsPromises.access(bytecodeModulesPath);
+    }
+    catch {
+        CLIDisplay.value(I18n.formatMessage("commands.build.warnings.noBytecodeModulesFolder", { contractName }), "", 2);
+        return;
+    }
+    const moduleFiles = await fsPromises.readdir(bytecodeModulesPath);
+    const mvFiles = moduleFiles.filter(f => f.endsWith(".mv"));
+    if (mvFiles.length === 0) {
+        CLIDisplay.value(I18n.formatMessage("commands.build.warnings.noMvFilesFound", { contractName }), "", 2);
+        return;
+    }
+    // Compute the package ID
+    const modulesBytesForHash = [];
+    const modulesBase64 = [];
+    for (const file of mvFiles) {
+        const modulePath = path.join(bytecodeModulesPath, file);
+        const moduleBytes = await fsPromises.readFile(modulePath);
+        modulesBytesForHash.push(moduleBytes);
+        modulesBase64.push(Converter.bytesToBase64(moduleBytes));
+    }
+    const concatenated = Buffer.concat(modulesBytesForHash);
+    const computedPackageIdBytes = Sha3.sum256(concatenated);
+    const computedPackageId = `${Converter.bytesToHex(computedPackageIdBytes, true)}`;
+    CLIDisplay.value(I18n.formatMessage("commands.build.labels.computedPackageId"), computedPackageId, 2);
+    // If multiple modules, store them as an array
+    const packageData = modulesBase64.length === 1 ? modulesBase64[0] : modulesBase64;
+    return {
+        contractName,
+        packageId: computedPackageId,
+        packageBytecode: packageData
+    };
+}
+/**
+ * Get the project root directory from a Move file path.
+ * @param moveFilePath The path to a Move source file.
+ * @returns The project root directory.
+ */
+function getProjectRoot(moveFilePath) {
+    return path.resolve(path.parse(moveFilePath).dir, "..");
+}
+/**
+ * Normalize paths and resolve working directory for cross-platform compatibility.
+ * @param inputGlob The input glob pattern
+ * @param outputJson The output JSON file path
+ * @returns Normalized paths and working directory
+ */
+function normalizePathsAndWorkingDir(inputGlob, outputJson) {
+    const executionDir = process.cwd();
+    // Improved path normalization with StringHelper
+    const normalizedGlob = StringHelper.trimTrailingSlashes(path.resolve(inputGlob).replace(/\\/g, "/"));
+    const normalizedOutput = path.resolve(outputJson);
+    return {
+        normalizedGlob,
+        normalizedOutput,
+        executionDir
+    };
+}
+//# sourceMappingURL=build.js.map