feat(cli): unboc utility to expose TVM disassembler via @tact-lang/…

…opcode library (#1259)

.github/workflows/tact.yml

@@ -173,6 +173,12 @@ jobs:
         run: |
           tact -e '(1 + 2 * (pow(3,4) - 2) << 1 & 0x54 | 33 >> 1) * 2 + 2'
 
+      - name: CLI Test | Check TVM disassembler flag
+        if: runner.os != 'Windows'
+        run: |
+          tact bin/test/success.tact
+          unboc bin/test/success_HelloWorld.code.boc
+
       - name: Test compatibility with tact-template
         run: |
           git clone https://github.com/tact-lang/tact-template.git

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Utility for logging errors in code that was supposed to be unreachable: PR [#991](https://github.com/tact-lang/tact/pull/991)
 - Ability to specify a compile-time message opcode expression: PR [#1188](https://github.com/tact-lang/tact/pull/1188)
 - The `VarInt16`, `VarInt32`, `VarUint16`, `VarUint32` integer serialization types: PR [#1186](https://github.com/tact-lang/tact/pull/1186)
+- `unboc`: a standalone CLI utility to expose Tact's TVM disassembler: PR [#1259](https://github.com/tact-lang/tact/pull/1259)
 
 ### Changed
 

bin/unboc.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const meowModule = import("meow");
+const { decompileAll } = require("@tact-lang/opcode");
+const { readFileSync } = require("fs");
+
+const unbocVersion = "0.0.1";
+
+void meowModule.then(
+    /** @param meow {import('meow/build/index')} */
+    (meow) => {
+        const cli = meow.default(
+            `
+    Usage
+      $ unboc [...flags] BOC-FILE
+
+    Flags
+      -v, --version               Print unboc version and exit
+      -h, --help                  Display this text and exit
+
+    Examples
+      $ unboc --version
+      ${unbocVersion}`,
+            {
+                importMeta: {
+                    url: new URL("file://" + __dirname + __filename).toString(),
+                },
+                description: `Command-line utility to disassemble a BoC (bag of cells) file with code and output TVM instructions to stdout`,
+                autoVersion: false,
+                flags: {
+                    version: { shortFlag: "v", type: "boolean" },
+                    help: { shortFlag: "h", type: "boolean" },
+                },
+                allowUnknownFlags: false,
+            },
+        );
+
+        // Show help regardless of other flags
+        if (cli.flags.help) {
+            cli.showHelp(0);
+        }
+
+        // Show version regardless of other flags
+        if (cli.flags.version) {
+            console.log(unbocVersion);
+            process.exit(0);
+        }
+
+        // Disallow specifying more than one boc file
+        if (cli.input.length > 1) {
+            console.error(
+                "Error: Only one BoC file can be specified at a time.",
+            );
+            cli.showHelp(30);
+        }
+
+        // Show help when all flags and inputs are empty
+        // Note, that version/help flags are already processed above and don't need to be mentioned here
+        if (cli.input.length === 0) {
+            cli.showHelp(0);
+        }
+
+        // Main command
+        try {
+            const boc = readFileSync(cli.input.at(0));
+            const disasmResult = decompileAll({ src: Buffer.from(boc) });
+            console.log(disasmResult);
+            process.exit(0);
+        } catch (error) {
+            console.error(error.message);
+            // https://nodejs.org/docs/v20.12.1/api/process.html#exit-codes
+            process.exit(30);
+        }
+    },
+);

cspell.json

@@ -120,6 +120,7 @@
     "Trunov",
     "typechecker",
     "uintptr",
+    "unboc",
     "uninit",
     "unixfs",
     "untypable",

knip.json

@@ -1,7 +1,13 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "entry": ["src/index.ts", "src/main.ts", "src/node.ts", "bin/tact.js"],
-  "project": ["src/**/*.ts", "bin/tact.js"],
+  "entry": [
+    "src/index.ts",
+    "src/main.ts",
+    "src/node.ts",
+    "bin/tact.js",
+    "bin/unboc.js"
+  ],
+  "project": ["src/**/*.ts", "bin/tact.js", "bin/unboc.js"],
   "ignore": [
     "src/grammar/ast.ts",
     "src/prettyPrinter.ts",

package.json

@@ -43,7 +43,8 @@
   ],
   "main": "./dist/main.js",
   "bin": {
-    "tact": "bin/tact.js"
+    "tact": "bin/tact.js",
+    "unboc": "bin/unboc.js"
   },
   "dependencies": {
     "@tact-lang/opcode": "^0.0.16",

tsconfig.eslint.json

@@ -9,7 +9,8 @@
     "examples/",
     "scripts/",
     "./jest.config.js",
-    "bin/tact.js"
+    "bin/tact.js",
+    "bin/unboc.js"
   ],
   "exclude": ["**/*.bind.ts", "src/test/**/output/**/*"]
 }