@semaphore-protocol/cli 4.0.0-beta.1 → 4.0.0-beta.11

package/README.md

@@ -46,23 +46,25 @@
     </h4>
 </div>
 
-| Setting up a project, although not particularly complex, can be a lengthy process for some people. The Semaphore CLI reduces the set-up time from a few minutes to a few seconds. In addition, it can also be used to obtain on-chain group data. |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Semaphore CLI simplifies the process of setting up Semaphore projects and retrieving on-chain group data, reducing setup time from minutes to seconds. |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ |
 
 ## 🛠 Install
 
-Install the `@semaphore-protocol/cli` package globally:
+To install Semaphore CLI globally:
 
 ```bash
 npm i -g @semaphore-protocol/cli
 ```
 
-or run specific commands with `npx`:
+Alternatively, you can use `npx` to run commands without installing the package globally:
 
 ```bash
 npx @semaphore-protocol/cli create my-app
 ```
 
+This command sets up a new project in the `my-app` directory using the `monorepo-ethers` template.
+
 ## 📜 Usage
 
 ```
@@ -82,3 +84,15 @@ Commands:
   get-proofs [options] [group-id]       Get the proofs of a group from a supported network (e.g. sepolia or arbitrum).
   help [command]                        Display help for a specific command.
 ```
+
+## 🌐 Supported Networks
+
+Semaphore CLI supports multiple Ethereum networks. Use the `get-groups` command to interact with groups on networks like Sepolia or Arbitrum.
+
+## 📦 Supported Templates
+
+When creating a new project, you can choose from several templates designed to integrate seamlessly with Semaphore's privacy protocols:
+
+-   **monorepo-ethers**: Hardhat + Next.js + SemaphoreEthers
+-   **monorepo-subgraph**: Hardhat + Next.js + SemaphoreSubgraph
+-   **contracts-hardhat**: Hardhat only, focused on smart contract development.

package/dist/index.js

@@ -2,14 +2,15 @@
 
 /**
  * @module @semaphore-protocol/cli
- * @version 4.0.0-beta.1
+ * @version 4.0.0-beta.11
  * @file A command line tool to set up your Semaphore project and get group data.
  * @copyright Ethereum Foundation 2024
  * @license MIT
  * @see [Github]{@link https://github.com/semaphore-protocol/semaphore/tree/main/packages/cli}
 */
 
-import { SemaphoreSubgraph, SemaphoreEthers, getSupportedNetworks } from '@semaphore-protocol/data';
+import { SemaphoreSubgraph, SemaphoreEthers } from '@semaphore-protocol/data';
+import { isSupportedNetwork, supportedNetworks } from '@semaphore-protocol/utils/networks';
 import chalk from 'chalk';
 import { program } from 'commander';
 import decompress from 'decompress';
@@ -28,10 +29,10 @@ import inquirer from 'inquirer';
 
 const cliRegistryURL = "https://registry.npmjs.org/-/package/@semaphore-protocol/cli/dist-tags";
 /**
- * Checks the registry directly via the API, if that fails, tries the slower `npm view [package] version` command.
- * This is important for users in environments where direct access to npm is blocked by a firewall, and packages are
- * provided exclusively via a private registry.
- * @param currentVersion The current version of the CLI.
+ * Checks for the latest version of the CLI tool against the registry. It first attempts to fetch the version directly
+ * via an API call. If this fails, possibly due to network restrictions, it falls back to using the `npm view` command.
+ * This method ensures that users behind a firewall or using a private registry can still check for updates.
+ * @param currentVersion The current version of the CLI being used.
  */
 async function checkLatestVersion(currentVersion) {
     let latestVersion;
@@ -54,6 +55,11 @@ async function checkLatestVersion(currentVersion) {
     }
 }
 
+/**
+ * A utility class for managing a CLI spinner. This class encapsulates the functionality of the `ora` spinner,
+ * providing methods to start and stop the spinner. It is used to give visual feedback to the user during operations
+ * that have a noticeable delay, such as network requests.
+ */
 class Spinner {
     constructor(text) {
         this.ora = ora({
@@ -71,8 +77,11 @@ class Spinner {
 }
 
 /**
- * Gets all group ids on the specified network
- * @param network The specified network
+ * Retrieves all group IDs from the Semaphore protocol on a specified network. This function first attempts to
+ * fetch the group IDs using the SemaphoreSubgraph interface. If that fails, it tries the SemaphoreEthers interface
+ * as a fallback. This dual-method approach ensures higher reliability in fetching data across different network conditions.
+ * @param network The blockchain network from which to fetch the group IDs.
+ * @returns A promise that resolves to an array of group IDs or null if an error occurs.
  */
 async function getGroupIds(network) {
     let groupIds;
@@ -98,6 +107,10 @@ async function getGroupIds(network) {
     return groupIds;
 }
 
+/**
+ * Prompts the user to input the name of their project. Provides a default name of "my-app".
+ * @returns A promise that resolves to the user's input for the project name.
+ */
 async function getProjectName() {
     const { projectName } = await inquirer.prompt({
         name: "projectName",
@@ -107,6 +120,12 @@ async function getProjectName() {
     });
     return projectName;
 }
+/**
+ * Prompts the user to select a template from a list of supported templates. Each template is presented
+ * with its value and name for better clarity.
+ * @param supportedTemplates An array of objects, each containing a 'value' and 'name' property for the template.
+ * @returns A promise that resolves to the selected template's value.
+ */
 async function getSupportedTemplate(supportedTemplates) {
     const { selectedTemplate } = await inquirer.prompt({
         name: "selectedTemplate",
@@ -120,6 +139,11 @@ async function getSupportedTemplate(supportedTemplates) {
     });
     return selectedTemplate;
 }
+/**
+ * Prompts the user to select a network from a list of supported networks.
+ * @param supportedNetworks An array of strings representing the supported networks.
+ * @returns A promise that resolves to the selected network.
+ */
 async function getSupportedNetwork(supportedNetworks) {
     const { selectedNetwork } = await inquirer.prompt({
         name: "selectedNetwork",
@@ -130,6 +154,11 @@ async function getSupportedNetwork(supportedNetworks) {
     });
     return selectedNetwork;
 }
+/**
+ * Prompts the user to select a group ID from a list of existing group IDs.
+ * @param groupIds An array of strings representing the group IDs.
+ * @returns A promise that resolves to the selected group ID.
+ */
 async function getGroupId(groupIds) {
     const { selectedGroupId } = await inquirer.prompt({
         name: "selectedGroupId",
@@ -141,9 +170,10 @@ async function getGroupId(groupIds) {
     return selectedGroupId;
 }
 
+// Define the path to the package.json file to extract metadata for the CLI.
 const packagePath = `${dirname(fileURLToPath(import.meta.url))}/..`;
 const { description, version } = JSON.parse(readFileSync(`${packagePath}/package.json`, "utf8"));
-const supportedNetworks = getSupportedNetworks();
+// List of supported templates for project creation.
 const supportedTemplates = [
     {
         value: "monorepo-ethers",
@@ -158,6 +188,7 @@ const supportedTemplates = [
         name: "Hardhat"
     }
 ];
+// Setup the CLI program with basic information and help text.
 program
     .name("semaphore")
     .description(description)
@@ -171,6 +202,7 @@ program
         console.info(`\n ${logSymbols.error}`, message);
     }
 });
+// Define the 'create' command to scaffold new Semaphore projects.
 program
     .command("create")
     .description("Create a Semaphore project with a supported template.")
@@ -196,15 +228,20 @@ program
     }
     spinner.start();
     await checkLatestVersion(version);
+    // Extract the template package into the project directory.
     await pacote.extract(`@semaphore-protocol/cli-template-${template}@${version}`, `${currentDirectory}/${projectDirectory}`);
+    // Decompress the template files after extraction.
     await decompress(`${currentDirectory}/${projectDirectory}/files.tgz`, `${currentDirectory}/${projectDirectory}`);
+    // Clean up the compressed file after extraction.
     unlinkSync(`${currentDirectory}/${projectDirectory}/files.tgz`);
+    // Copy the example environment file to the actual environment file.
     copyFileSync(`${currentDirectory}/${projectDirectory}/.env.example`, `${currentDirectory}/${projectDirectory}/.env`);
     spinner.stop();
     console.info(`\n ${logSymbols.success}`, `Your project is ready!\n`);
     console.info(` Please, install your dependencies by running:\n`);
     console.info(`   ${chalk.cyan("cd")} ${projectDirectory}`);
     console.info(`   ${chalk.cyan("yarn install")}\n`);
+    // Read the package.json to list available npm scripts.
     const { scripts } = JSON.parse(readFileSync(`${currentDirectory}/${projectDirectory}/package.json`, "utf8"));
     if (scripts) {
         console.info(` Available scripts:\n`);
@@ -221,9 +258,9 @@ program
     .allowExcessArguments(false)
     .action(async ({ network }) => {
     if (!network) {
-        network = await getSupportedNetwork(supportedNetworks);
+        network = await getSupportedNetwork(Object.keys(supportedNetworks));
     }
-    if (!supportedNetworks.includes(network)) {
+    if (!isSupportedNetwork(network)) {
         console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`);
         return;
     }
@@ -245,9 +282,9 @@ program
     .allowExcessArguments(false)
     .action(async (groupId, { network }) => {
     if (!network) {
-        network = await getSupportedNetwork(supportedNetworks);
+        network = await getSupportedNetwork(Object.keys(supportedNetworks));
     }
-    if (!supportedNetworks.includes(network)) {
+    if (!isSupportedNetwork(network)) {
         console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`);
         return;
     }
@@ -299,9 +336,9 @@ program
     .allowExcessArguments(false)
     .action(async (groupId, { network }) => {
     if (!network) {
-        network = await getSupportedNetwork(supportedNetworks);
+        network = await getSupportedNetwork(Object.keys(supportedNetworks));
     }
-    if (!supportedNetworks.includes(network)) {
+    if (!isSupportedNetwork(network)) {
         console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`);
         return;
     }
@@ -351,9 +388,9 @@ program
     .allowExcessArguments(false)
     .action(async (groupId, { network }) => {
     if (!network) {
-        network = await getSupportedNetwork(supportedNetworks);
+        network = await getSupportedNetwork(Object.keys(supportedNetworks));
     }
-    if (!supportedNetworks.includes(network)) {
+    if (!isSupportedNetwork(network)) {
         console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`);
         return;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@semaphore-protocol/cli",
   "type": "module",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.11",
   "description": "A command line tool to set up your Semaphore project and get group data.",
   "license": "MIT",
   "bin": {
@@ -31,15 +31,18 @@
     "access": "public"
   },
   "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
     "@types/figlet": "^1.5.8",
     "@types/inquirer": "^9.0.7",
     "@types/pacote": "^11.1.8",
     "@types/semver": "^7.5.8",
-    "rollup-plugin-cleanup": "^3.2.1",
-    "rollup-plugin-typescript2": "^0.36.0"
+    "rimraf": "^5.0.5",
+    "rollup": "^4.12.0",
+    "rollup-plugin-cleanup": "^3.2.1"
   },
   "dependencies": {
-    "@semaphore-protocol/data": "4.0.0-beta.1",
+    "@semaphore-protocol/data": "4.0.0-beta.11",
+    "@semaphore-protocol/utils": "4.0.0-beta.11",
     "axios": "^1.6.7",
     "boxen": "^7.1.1",
     "chalk": "^5.3.0",

package/src/checkLatestVersion.ts

@@ -7,10 +7,10 @@ import { lt as semverLt } from "semver"
 const cliRegistryURL = "https://registry.npmjs.org/-/package/@semaphore-protocol/cli/dist-tags"
 
 /**
- * Checks the registry directly via the API, if that fails, tries the slower `npm view [package] version` command.
- * This is important for users in environments where direct access to npm is blocked by a firewall, and packages are
- * provided exclusively via a private registry.
- * @param currentVersion The current version of the CLI.
+ * Checks for the latest version of the CLI tool against the registry. It first attempts to fetch the version directly
+ * via an API call. If this fails, possibly due to network restrictions, it falls back to using the `npm view` command.
+ * This method ensures that users behind a firewall or using a private registry can still check for updates.
+ * @param currentVersion The current version of the CLI being used.
  */
 export default async function checkLatestVersion(currentVersion: string) {
     let latestVersion: string

package/src/getGroupIds.ts

@@ -1,12 +1,16 @@
 import { SemaphoreSubgraph, SemaphoreEthers } from "@semaphore-protocol/data"
+import { SupportedNetwork } from "@semaphore-protocol/utils"
 import logSymbols from "log-symbols"
 import Spinner from "./spinner.js"
 
 /**
- * Gets all group ids on the specified network
- * @param network The specified network
+ * Retrieves all group IDs from the Semaphore protocol on a specified network. This function first attempts to
+ * fetch the group IDs using the SemaphoreSubgraph interface. If that fails, it tries the SemaphoreEthers interface
+ * as a fallback. This dual-method approach ensures higher reliability in fetching data across different network conditions.
+ * @param network The blockchain network from which to fetch the group IDs.
+ * @returns A promise that resolves to an array of group IDs or null if an error occurs.
  */
-export default async function getGroupIds(network): Promise<string[]> {
+export default async function getGroupIds(network: SupportedNetwork): Promise<string[]> {
     let groupIds: string[]
 
     const spinner = new Spinner("Fetching groups")

package/src/index.ts

@@ -1,4 +1,5 @@
-import { GroupResponse, SemaphoreEthers, SemaphoreSubgraph, getSupportedNetworks } from "@semaphore-protocol/data"
+import { GroupResponse, SemaphoreEthers, SemaphoreSubgraph } from "@semaphore-protocol/data"
+import { isSupportedNetwork, supportedNetworks } from "@semaphore-protocol/utils/networks"
 import chalk from "chalk"
 import { program } from "commander"
 import decompress from "decompress"
@@ -13,11 +14,11 @@ import getGroupIds from "./getGroupIds.js"
 import { getGroupId, getProjectName, getSupportedNetwork, getSupportedTemplate } from "./inquirerPrompts.js"
 import Spinner from "./spinner.js"
 
+// Define the path to the package.json file to extract metadata for the CLI.
 const packagePath = `${dirname(fileURLToPath(import.meta.url))}/..`
 const { description, version } = JSON.parse(readFileSync(`${packagePath}/package.json`, "utf8"))
 
-const supportedNetworks = getSupportedNetworks()
-
+// List of supported templates for project creation.
 const supportedTemplates = [
     {
         value: "monorepo-ethers",
@@ -33,6 +34,7 @@ const supportedTemplates = [
     }
 ]
 
+// Setup the CLI program with basic information and help text.
 program
     .name("semaphore")
     .description(description)
@@ -47,6 +49,7 @@ program
         }
     })
 
+// Define the 'create' command to scaffold new Semaphore projects.
 program
     .command("create")
     .description("Create a Semaphore project with a supported template.")
@@ -79,15 +82,19 @@ program
 
         await checkLatestVersion(version)
 
+        // Extract the template package into the project directory.
         await pacote.extract(
             `@semaphore-protocol/cli-template-${template}@${version}`,
             `${currentDirectory}/${projectDirectory}`
         )
 
+        // Decompress the template files after extraction.
         await decompress(`${currentDirectory}/${projectDirectory}/files.tgz`, `${currentDirectory}/${projectDirectory}`)
 
+        // Clean up the compressed file after extraction.
         unlinkSync(`${currentDirectory}/${projectDirectory}/files.tgz`)
 
+        // Copy the example environment file to the actual environment file.
         copyFileSync(
             `${currentDirectory}/${projectDirectory}/.env.example`,
             `${currentDirectory}/${projectDirectory}/.env`
@@ -100,6 +107,7 @@ program
         console.info(`   ${chalk.cyan("cd")} ${projectDirectory}`)
         console.info(`   ${chalk.cyan("yarn install")}\n`)
 
+        // Read the package.json to list available npm scripts.
         const { scripts } = JSON.parse(readFileSync(`${currentDirectory}/${projectDirectory}/package.json`, "utf8"))
 
         if (scripts) {
@@ -122,10 +130,10 @@ program
     .allowExcessArguments(false)
     .action(async ({ network }) => {
         if (!network) {
-            network = await getSupportedNetwork(supportedNetworks)
+            network = await getSupportedNetwork(Object.keys(supportedNetworks))
         }
 
-        if (!supportedNetworks.includes(network)) {
+        if (!isSupportedNetwork(network)) {
             console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`)
             return
         }
@@ -152,10 +160,10 @@ program
     .allowExcessArguments(false)
     .action(async (groupId, { network }) => {
         if (!network) {
-            network = await getSupportedNetwork(supportedNetworks)
+            network = await getSupportedNetwork(Object.keys(supportedNetworks))
         }
 
-        if (!supportedNetworks.includes(network)) {
+        if (!isSupportedNetwork(network)) {
             console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`)
             return
         }
@@ -220,10 +228,10 @@ program
     .allowExcessArguments(false)
     .action(async (groupId, { network }) => {
         if (!network) {
-            network = await getSupportedNetwork(supportedNetworks)
+            network = await getSupportedNetwork(Object.keys(supportedNetworks))
         }
 
-        if (!supportedNetworks.includes(network)) {
+        if (!isSupportedNetwork(network)) {
             console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`)
             return
         }
@@ -286,10 +294,10 @@ program
     .allowExcessArguments(false)
     .action(async (groupId, { network }) => {
         if (!network) {
-            network = await getSupportedNetwork(supportedNetworks)
+            network = await getSupportedNetwork(Object.keys(supportedNetworks))
         }
 
-        if (!supportedNetworks.includes(network)) {
+        if (!isSupportedNetwork(network)) {
             console.info(`\n ${logSymbols.error}`, `error: the network '${network}' is not supported\n`)
             return
         }

package/src/inquirerPrompts.ts

@@ -1,5 +1,9 @@
 import inquirer from "inquirer"
 
+/**
+ * Prompts the user to input the name of their project. Provides a default name of "my-app".
+ * @returns A promise that resolves to the user's input for the project name.
+ */
 export async function getProjectName() {
     const { projectName } = await inquirer.prompt({
         name: "projectName",
@@ -10,6 +14,12 @@ export async function getProjectName() {
     return projectName
 }
 
+/**
+ * Prompts the user to select a template from a list of supported templates. Each template is presented
+ * with its value and name for better clarity.
+ * @param supportedTemplates An array of objects, each containing a 'value' and 'name' property for the template.
+ * @returns A promise that resolves to the selected template's value.
+ */
 export async function getSupportedTemplate(supportedTemplates: { value: string; name: string }[]) {
     const { selectedTemplate } = await inquirer.prompt({
         name: "selectedTemplate",
@@ -24,6 +34,11 @@ export async function getSupportedTemplate(supportedTemplates: { value: string;
     return selectedTemplate
 }
 
+/**
+ * Prompts the user to select a network from a list of supported networks.
+ * @param supportedNetworks An array of strings representing the supported networks.
+ * @returns A promise that resolves to the selected network.
+ */
 export async function getSupportedNetwork(supportedNetworks: string[]) {
     const { selectedNetwork } = await inquirer.prompt({
         name: "selectedNetwork",
@@ -35,6 +50,11 @@ export async function getSupportedNetwork(supportedNetworks: string[]) {
     return selectedNetwork
 }
 
+/**
+ * Prompts the user to select a group ID from a list of existing group IDs.
+ * @param groupIds An array of strings representing the group IDs.
+ * @returns A promise that resolves to the selected group ID.
+ */
 export async function getGroupId(groupIds: string[]) {
     const { selectedGroupId } = await inquirer.prompt({
         name: "selectedGroupId",

package/src/spinner.ts

@@ -1,5 +1,10 @@
 import ora, { Ora } from "ora"
 
+/**
+ * A utility class for managing a CLI spinner. This class encapsulates the functionality of the `ora` spinner,
+ * providing methods to start and stop the spinner. It is used to give visual feedback to the user during operations
+ * that have a noticeable delay, such as network requests.
+ */
 export default class Spinner {
     private ora: Ora