Merge pull request #121 from pixelplex/feature/help-commands

feat: add help commands

src/cli/build.ts

@@ -3,6 +3,7 @@ import { findCompiles, selectFile } from '../utils';
 import { UIProvider } from '../ui/UIProvider';
 import arg from 'arg';
 import { buildAll, buildOne } from '../build';
+import { helpArgs, helpMessages } from './constants';
 
 export async function selectCompile(ui: UIProvider, args: Args) {
     return await selectFile(await findCompiles(), {
@@ -15,7 +16,12 @@ export async function selectCompile(ui: UIProvider, args: Args) {
 export const build: Runner = async (args: Args, ui: UIProvider) => {
     const localArgs = arg({
         '--all': Boolean,
+        ...helpArgs,
     });
+    if (localArgs['--help']) {
+        ui.write(helpMessages['build']);
+        return;
+    }
 
     if (localArgs['--all']) {
         await buildAll();

src/cli/constants.ts

@@ -0,0 +1,87 @@
+export const templateTypes: { name: string; value: string }[] = [
+    {
+        name: 'An empty contract (FunC)',
+        value: 'func-empty',
+    },
+    {
+        name: 'A simple counter contract (FunC)',
+        value: 'func-counter',
+    },
+    {
+        name: 'An empty contract (TACT)',
+        value: 'tact-empty',
+    },
+    {
+        name: 'A simple counter contract (TACT)',
+        value: 'tact-counter',
+    },
+];
+
+export const helpArgs = { '--help': Boolean };
+export const helpMessages = {
+    help: `Usage: blueprint help [command]
+
+Displays this message if no command is specified, or displays detailed help for the specified command.
+
+Blueprint is generally invoked as follows: blueprint [command] [command-args] [flags]
+
+List of available commands:
+- create
+- run
+- build
+- custom
+- help
+- test
+- verify
+- convert`,
+    create: `Usage: blueprint create [contract name] [flags]
+
+Creates a new contract together with supporting files according to a template.
+
+Contract name must be specified in PascalCase and may only include characters a-z, A-Z, 0-9. If not specified on the command line, it will be asked interactively.
+
+Flags:
+--type <type> - specifies the template type to use when creating the contract. If not specified on the command line, it will be asked interactively.
+List of available types:
+${templateTypes.map((t) => `${t.value} - ${t.name}`).join('\n')}`,
+    run: `Usage: blueprint run [script name] [flags]
+
+Runs a script from the scripts directory.
+
+Script name is matched (ignoring case) to a file in the scripts directory. If not specified on the command line, the available scripts will be presented interactively.
+
+Flags:
+--mainnet, --testnet - specifies the network to use when running the script. If not specified on the command line, it will be asked interactively.
+--custom [api-endpoint] - indicates that a custom API should be used when running the script, and the API URL optionally. (example: https://testnet.toncenter.com/api/v2/)
+--custom-version - specifies the API version to use with the custom API. Options: v2 (defualt), v4.
+--custom-key - specifies the API key to use with the custom API, can only be used with API v2.
+--custom-type - specifies the network type to be indicated to scripts. Options: custom (default), mainnet, testnet.
+--tonconnect, --tonhub, --deeplink, --mnemonic - specifies the deployer to use when running the script. If not specified on the command line, it will be asked interactively.
+--tonscan, --tonviewer, --toncx, --dton - specifies the network explorer to use when displaying links to the deployed contracts. Default: tonscan.`,
+    build: `Usage: blueprint build [contract name] [flags]
+
+Builds the specified contract according to the respective .compile.ts file. If the contract is written in TACT, all TACT-generated files (wrapper class, etc) will be placed in the build/<contract name> folder.
+
+If contract name is not specified on the command line, the buildable contracts (that have the respective .compile.ts files under wrappers directory) will be presented interactively, unless --all flag is specified.
+
+Flags:
+--all - builds all buildable contracts instead of just one.`,
+    set: `Usage: blueprint set <key> [value]
+Available keys:
+- func - overrides @ton-community/func-js-bin version, effectively setting the func version. The required version may be passed as the value, otherwise available versions will be displayed.`,
+    test: `Usage: blueprint test
+
+Just runs \`npm test\`, which by default runs \`jest\`.`,
+    verify: `Usage: blueprint verify [contract name] [flags]
+
+Builds a contract (similar to build command) and verifies it on https://verifier.ton.org. The contract must be already deployed on the network. If the contract's name is not specified on the command line, it will be asked interactively.
+
+Flags:
+--mainnet, --testnet - specifies the network to use when running the script. If not specified on the command line, it will be asked interactively.
+--custom [api-endpoint] - indicates that a custom API should be used when running the script, and the API URL optionally. (example: https://testnet.toncenter.com/api/v2/) Requires --custom-type to be specified.
+--custom-version - specifies the API version to use with the custom API. Options: v2 (defualt), v4.
+--custom-key - specifies the API key to use with the custom API, can only be used with API v2.
+--custom-type - specifies the network type to be indicated to scripts. Options: mainnet, testnet.`,
+    convert: `Usage: blueprint convert [path to build script]
+Atempts to convert legacy bash build script to a blueprint compile wrapper.`,
+} satisfies { [name: string]: string };

src/cli/convert.ts

@@ -6,6 +6,7 @@ import { argSpec } from '../network/createNetworkProvider';
 import { executeTemplate, TEMPLATES_DIR } from '../template';
 import { WRAPPERS_DIR } from '../paths';
 import { Args, Runner } from './Runner';
+import { helpArgs, helpMessages } from './constants';
 
 function createWrapperName(old: string) {
     return old
@@ -90,7 +91,12 @@ function parseCompileString(str: string, src_dir: string, ui: UIProvider) {
 }
 
 export const convert: Runner = async (args: Args, ui: UIProvider) => {
-    const localArgs = arg(argSpec);
+    const localArgs = arg({ ...argSpec, ...helpArgs });
+    if (localArgs['--help']) {
+        ui.write(helpMessages['convert']);
+        return;
+    }
+
     let filePath: string;
     if (localArgs._.length < 2) {
         filePath = await ui.input('Please specify path to convert from:');

src/cli/create.ts

@@ -6,6 +6,7 @@ import { selectOption } from '../utils';
 import arg from 'arg';
 import { UIProvider } from '../ui/UIProvider';
 import { buildOne } from '../build';
+import { helpArgs, helpMessages } from './constants';
 
 function toSnakeCase(v: string): string {
     const r = v.replace(/[A-Z]/g, (sub) => '_' + sub.toLowerCase());
@@ -69,7 +70,12 @@ export const templateTypes: { name: string; value: string }[] = [
 export const create: Runner = async (args: Args, ui: UIProvider) => {
     const localArgs = arg({
         '--type': String,
+        ...helpArgs,
     });
+    if (localArgs['--help']) {
+        ui.write(helpMessages['create']);
+        return;
+    }
 
     const name =
         localArgs._.length > 1 && localArgs._[1].trim().length > 0

src/cli/help.ts

@@ -1,74 +1,6 @@
 import { UIProvider } from '../ui/UIProvider';
 import { Args, Runner } from './Runner';
-import { templateTypes } from './create';
-
-const helpMessages: { [name: string]: string } = {
-    help: `Usage: blueprint help [command]
-
-Displays this message if no command is specified, or displays detailed help for the specified command.
-
-Blueprint is generally invoked as follows: blueprint [command] [command-args] [flags]
-
-List of available commands:
-- create
-- run
-- build
-- custom
-- help
-- test
-- verify
-- convert`,
-    create: `Usage: blueprint create [contract name] [flags]
-
-Creates a new contract together with supporting files according to a template.
-
-Contract name must be specified in PascalCase and may only include characters a-z, A-Z, 0-9. If not specified on the command line, it will be asked interactively.
-
-Flags:
---type <type> - specifies the template type to use when creating the contract. If not specified on the command line, it will be asked interactively.
-List of available types:
-${templateTypes.map((t) => `${t.value} - ${t.name}`).join('\n')}`,
-    run: `Usage: blueprint run [script name] [flags]
-
-Runs a script from the scripts directory.
-
-Script name is matched (ignoring case) to a file in the scripts directory. If not specified on the command line, the available scripts will be presented interactively.
-
-Flags:
---mainnet, --testnet - specifies the network to use when running the script. If not specified on the command line, it will be asked interactively.
---custom [api-endpoint] - indicates that a custom API should be used when running the script, and the API URL optionally. (example: https://testnet.toncenter.com/api/v2/)
---custom-version - specifies the API version to use with the custom API. Options: v2 (defualt), v4.
---custom-key - specifies the API key to use with the custom API, can only be used with API v2.
---custom-type - specifies the network type to be indicated to scripts. Options: custom (default), mainnet, testnet.
---tonconnect, --tonhub, --deeplink, --mnemonic - specifies the deployer to use when running the script. If not specified on the command line, it will be asked interactively.
---tonscan, --tonviewer, --toncx, --dton - specifies the network explorer to use when displaying links to the deployed contracts. Default: tonscan.`,
-    build: `Usage: blueprint build [contract name] [flags]
-
-Builds the specified contract according to the respective .compile.ts file. If the contract is written in TACT, all TACT-generated files (wrapper class, etc) will be placed in the build/<contract name> folder.
-
-If contract name is not specified on the command line, the buildable contracts (that have the respective .compile.ts files under wrappers directory) will be presented interactively, unless --all flag is specified.
-
-Flags:
---all - builds all buildable contracts instead of just one.`,
-    set: `Usage: blueprint set <key> [value]
-Available keys:
-- func - overrides @ton-community/func-js-bin version, effectively setting the func version. The required version may be passed as the value, otherwise available versions will be displayed.`,
-    test: `Usage: blueprint test
-
-Just runs \`npm test\`, which by default runs \`jest\`.`,
-    verify: `Usage: blueprint verify [contract name] [flags]
-
-Builds a contract (similar to build command) and verifies it on https://verifier.ton.org. The contract must be already deployed on the network. If the contract's name is not specified on the command line, it will be asked interactively.
-
-Flags:
---mainnet, --testnet - specifies the network to use when running the script. If not specified on the command line, it will be asked interactively.
---custom [api-endpoint] - indicates that a custom API should be used when running the script, and the API URL optionally. (example: https://testnet.toncenter.com/api/v2/) Requires --custom-type to be specified.
---custom-version - specifies the API version to use with the custom API. Options: v2 (defualt), v4.
---custom-key - specifies the API key to use with the custom API, can only be used with API v2.
---custom-type - specifies the network type to be indicated to scripts. Options: mainnet, testnet.`,
-    convert: `Usage: blueprint convert [path to build script]
-Atempts to convert legacy bash build script to a blueprint compile wrapper.`,
-};
+import { helpMessages } from './constants';
 
 export let additionalHelpMessages: Record<string, string> = {};
 

src/cli/run.ts

@@ -3,9 +3,14 @@ import { createNetworkProvider, argSpec } from '../network/createNetworkProvider
 import { findScripts, selectFile } from '../utils';
 import { UIProvider } from '../ui/UIProvider';
 import arg from 'arg';
+import { helpArgs, helpMessages } from './constants';
 
 export const run: Runner = async (args: Args, ui: UIProvider, context: RunnerContext) => {
-    const localArgs = arg(argSpec);
+    const localArgs = arg({ ...argSpec, ...helpArgs });
+    if (localArgs['--help']) {
+        ui.write(helpMessages['run']);
+        return;
+    }
 
     const { module: mod } = await selectFile(await findScripts(), {
         ui,

src/cli/set.ts

@@ -3,6 +3,8 @@ import { UIProvider } from '../ui/UIProvider';
 import { readFile, writeFile } from 'fs/promises';
 import { exec } from 'node:child_process';
 import path from 'path';
+import arg from 'arg';
+import { helpArgs, helpMessages } from './constants';
 
 const getVersions = (pkg: string, ui: UIProvider): Promise<string[]> => {
     return new Promise((resolve, reject) => {
@@ -54,6 +56,12 @@ const install = (cmd: string, ui: UIProvider): Promise<void> => {
 }
 
 export const set: Runner = async (args: Args, ui: UIProvider) => {
+    const localArgs = arg(helpArgs);
+    if (localArgs['--help']) {
+        ui.write(helpMessages['set']);
+        return;
+    }
+
     if (args._.length < 2) {
         throw new Error('Please pass a key');
     }

src/cli/test.ts

@@ -1,6 +1,14 @@
 import { Runner } from './Runner';
 import { execSync } from 'child_process';
+import arg from 'arg';
+import { helpArgs, helpMessages } from './constants';
+
+export const test: Runner = async (args, ui) => {
+    const localArgs = arg(helpArgs);
+    if (localArgs['--help']) {
+        ui.write(helpMessages['test']);
+        return;
+    }
 
-export const test: Runner = async () => {
     execSync('npm test', { stdio: 'inherit' });
 };

src/cli/verify.ts

@@ -7,6 +7,7 @@ import { argSpec, createNetworkProvider } from '../network/createNetworkProvider
 import { selectCompile } from './build';
 import { sleep } from '../utils';
 import arg from 'arg';
+import { helpArgs, helpMessages } from './constants';
 
 type FuncCompilerSettings = {
     compiler: 'func';
@@ -166,7 +167,11 @@ async function lookupCodeHash(hash: Buffer, ui: UIProvider, retryCount: number =
 }
 
 export const verify: Runner = async (args: Args, ui: UIProvider, context: RunnerContext) => {
-    const localArgs = arg(argSpec);
+    const localArgs = arg({ ...argSpec, ...helpArgs });
+    if (localArgs['--help']) {
+        ui.write(helpMessages['verify']);
+        return;
+    }
 
     const sel = await selectCompile(ui, localArgs);