Lightnet error and edge cases handling. (#597)

Co-authored-by: Barrie Byron <[email protected]>

CHANGELOG.md

@@ -17,6 +17,19 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+### Breaking changes
+
+- Lightnet error and edge cases handling. [#597](https://github.com/o1-labs/zkapp-cli/pull/597)
+  - We removed common `--debug` CLI option in favor of [DEBUG](https://www.npmjs.com/package/debug) environment variable presence.
+  - From now on, in order to enable debug logging, you must set `DEBUG` environment variable to `<namespace>` value.
+    - Where `<namespace>` can be one of the following:
+      - `*`
+      - `zk:*`
+      - `zk:lightnet`
+    - Example: `DEBUG=zk:lightnet zk lightnet start`
+    - For details about the `DEBUG` environment variable, see Debug [Usage](https://www.npmjs.com/package/debug#usage).
+  - This improved debug logging capabilities can be leveraged with other parts of the zkApp CLI in the future.
+
 ### Changed
 
 - Improve CLI error handling. [#591](https://github.com/o1-labs/zkapp-cli/pull/591)

package.json

@@ -56,6 +56,7 @@
   },
   "dependencies": {
     "chalk": "^5.3.0",
+    "debug": "^4.3.4",
     "decompress": "^4.2.1",
     "enquirer": "^2.4.1",
     "envinfo": "^7.11.1",
@@ -73,17 +74,16 @@
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@playwright/test": "^1.41.2",
+    "@playwright/test": "^1.42.1",
     "@shimkiv/cli-testing-library": "^0.1.7",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^29.5.12",
-    "@typescript-eslint/eslint-plugin": "^7.0.1",
-    "@typescript-eslint/parser": "^7.0.1",
+    "@typescript-eslint/eslint-plugin": "^7.1.0",
+    "@typescript-eslint/parser": "^7.1.0",
     "cross-env": "^7.0.3",
-    "eslint": "^8.56.0",
+    "eslint": "^8.57.0",
     "eslint-plugin-o1js": "^0.4.0",
     "execa": "^8.0.1",
-    "fkill": "^9.0.0",
     "husky": "^9.0.11",
     "jest": "^29.7.0",
     "lint-staged": "^15.2.2",

src/bin/index.js

@@ -25,17 +25,6 @@ import system from '../lib/system.js';
 const __filename = url.fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const commonOptions = {
-  debug: {
-    alias: 'd',
-    demand: false,
-    boolean: true,
-    hidden: false,
-    default: false,
-    description: 'Whether to print the debug information.',
-  },
-};
-
 yargs(hideBin(process.argv))
   .scriptName(chalk.green('zk'))
   .usage('Usage: $0 <command> [options]')
@@ -176,7 +165,7 @@ function lightnetCli() {
       yargs
         .command(
           [
-            'start [mode] [type] [proof-level] [mina-branch] [archive] [sync] [pull] [mina-log-level] [debug]',
+            'start [mode] [type] [proof-level] [mina-branch] [archive] [sync] [pull] [mina-log-level]',
           ],
           'Start the lightweight Mina blockchain network Docker container.',
           {
@@ -256,12 +245,11 @@ function lightnetCli() {
               default: 'Trace',
               description: 'Mina processes logging level to use.',
             },
-            ...commonOptions,
           },
           async (argv) => await lightnetStart(argv)
         )
         .command(
-          ['stop [save-logs] [clean-up] [debug]'],
+          ['stop [save-logs] [clean-up]'],
           'Stop the lightweight Mina blockchain network Docker container and perform the cleanup.',
           {
             'save-logs': {
@@ -282,37 +270,26 @@ function lightnetCli() {
               description:
                 'Whether to remove the Docker container, dangling Docker images, consumed Docker volume, and the blockchain network configuration.',
             },
-            ...commonOptions,
           },
           async (argv) => await lightnetStop(argv)
         )
         .command(
-          ['status [debug]'],
+          ['status'],
           'Get the lightweight Mina blockchain network status.',
-          {
-            ...commonOptions,
-          },
-          async (argv) =>
-            await lightnetStatus({
-              preventDockerEngineAvailabilityCheck: false,
-              debug: argv.debug,
-            })
+          async () => await lightnetStatus()
         )
         .command(
           ['logs <sub-command> [options]'],
           'Handle the lightweight Mina blockchain network Docker container processes logs.',
           (yargs) => {
             yargs
               .command(
-                ['save [debug]'],
+                ['save'],
                 'Save the lightweight Mina blockchain network Docker container processes logs to the host file system.',
-                {
-                  ...commonOptions,
-                },
-                async (argv) => await lightnetSaveLogs(argv)
+                async () => await lightnetSaveLogs()
               )
               .command(
-                ['follow [process] [debug]'],
+                ['follow [process]'],
                 'Follow one of the lightweight Mina blockchain network Docker container processes logs.',
                 {
                   process: {
@@ -326,14 +303,13 @@ function lightnetCli() {
                     description:
                       'The name of the Docker container process to follow the logs of.',
                   },
-                  ...commonOptions,
                 },
                 async (argv) => await lightnetFollowLogs(argv)
               );
           }
         )
         .command(
-          ['explorer [use] [list] [debug]'],
+          ['explorer [use] [list]'],
           'Launch the lightweight Mina explorer.',
           {
             use: {
@@ -354,7 +330,6 @@ function lightnetCli() {
               description:
                 'Whether to list the available versions of the lightweight Mina explorer.',
             },
-            ...commonOptions,
           },
           async (argv) => await lightnetExplorer(argv)
         );

src/lib/helpers.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import net from 'net';
 import fetch from 'node-fetch';
 import ora from 'ora';
 
@@ -43,4 +44,46 @@ export async function isMinaGraphQlEndpointAvailable(endpoint) {
   }
 }
 
+/**
+ * Checks if a single port is available.
+ * @param {number} port The port number to check.
+ * @returns {Promise<{port: number, busy: boolean}>} A promise that resolves with an object containing the port number and a boolean indicating if the port is busy.
+ */
+export async function checkLocalPortAvailability(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.listen(port, '127.0.0.1');
+    server.on('listening', () => {
+      server.close();
+      resolve({ port, busy: false });
+    });
+    server.on('error', () => {
+      resolve({ port, busy: true });
+    });
+  });
+}
+
+/**
+ * Checks multiple ports for availability and identifies any that are not.
+ * @param {number[]} ports An array of port numbers to check.
+ * @returns {Promise<{error: boolean, message: string}>} A promise that resolves with an object containing an error flag and a message indicating the result.
+ */
+export async function checkLocalPortsAvailability(ports) {
+  const checks = ports.map((port) => checkLocalPortAvailability(port));
+  const results = await Promise.all(checks);
+  const busyPorts = results
+    .filter((result) => result.busy)
+    .map((result) => result.port);
+  if (busyPorts.length > 0) {
+    return {
+      error: true,
+      message:
+        `The following local ports are required but unavailable at this time: ${busyPorts.join(', ')}`.trim() +
+        '\nYou can close applications that use these ports and try again.',
+    };
+  } else {
+    return { error: false };
+  }
+}
+
 export default step;