feat: add script argument to repl

[willemneal]

Many users end up creating their own scripts which hack together the information provided from near-cli. Currently accepts javascript or typescript. The script file just needs to export a main function.

This is particularly useful for using a ledger in a script.

You can also pass arguments after --

E.g.

near repl -s ./scripts/deploy_contracts.js --accountId test.near -- arg

[willemneal]

@volovyk-s @vgrichina

[volovyks]

@willemneal I can see that you are improving this PR constantly. Please, ping me when it will be ready for review.

[willemneal]

@volovyk-s Was just about to! It should be ready to go. I just can't trigger CI.

[volovyks]

Suggested change

	console.error(error);
	process.exit(1);
	throw error;

[willemneal]

I found that throwing the error would cause all documentation to print.

[volovyks]

Suggested change

	console.error(error);
	process.exit(1);
	throw error;

[volovyks]

@willemneal run yarn fix please. I will check the CI.

[willemneal]

@volovyk-s. If I throw the error I get

near repl

launch interactive Node.js shell with NEAR connection available to use.
The repl's initial context contains `nearAPI`, `near` and `account`
if an accountId cli argument is provided.
To load a script into the repl use  ".load script.js".

Use the the 'script' option to pass context to a provided
javascript/typescript file which exports a main function.
Arguments after "--" are passed to script

USAGE:
    near repl --accountId bob
    > console.log(account)
    > .load script.js

    near repl -s ./scripts/delpoyContracts.js
    near repl -s ./scripts/run.js -- test.near bob.test.near
    near repl -s ./script.ts


Options:
      --help                     Show help  [boolean]
      --version                  Show version number  [boolean]
      --nodeUrl, --node_url      NEAR node URL  [string] [default: "https://rpc.testnet.near.org"]
      --networkId, --network_id  NEAR network ID, allows using different keys based on network  [string] [default: "testnet"]
      --helperUrl                NEAR contract helper URL  [string]
      --keyPath                  Path to master account key  [string]
      --accountId, --account_id  Unique identifier for the account  [string]
      --useLedgerKey             Use Ledger for signing with given HD key path  [string] [default: "44'/397'/0'/0'/1'"]
      --seedPhrase               Seed phrase mnemonic  [string]
      --seedPath                 HD path derivation  [string] [default: "m/44'/397'/0'"]
      --walletUrl                Website for NEAR Wallet  [string]
      --contractName             Account name of contract  [string]
      --masterAccount            Master account used when creating new accounts  [string]
      --helperAccount            Expected top-level account for a network  [string]
  -v, --verbose                  Prints out verbose output  [boolean] [default: false]
  -f, --force                    Forcefully execute the desired action even if it is unsafe to do so  [boolean] [default: false]
  -s, --script                   'repl': Path to a JS/TS file which exports an async function `main`,
                                 which takes a `context` object.  [string]

Error: Cannot find module '/Users/willem/c/near-cli/test/script_tet'
Require stack:
- /Users/willem/c/near-cli/commands/repl.js
- /Users/willem/c/near-cli/bin/near-cli.js
- /Users/willem/c/near-cli/bin/near
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:885:15)
    at Function.Module._load (internal/modules/cjs/loader.js:730:27)
    at Module.require (internal/modules/cjs/loader.js:957:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at loadScript (/Users/willem/c/near-cli/commands/repl.js:68:16)
    at Object.handler (/Users/willem/c/near-cli/commands/repl.js:39:34)
    at processTicksAndRejections (internal/process/task_queues.js:95:5) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/Users/willem/c/near-cli/commands/repl.js',
    '/Users/willem/c/near-cli/bin/near-cli.js',
    '/Users/willem/c/near-cli/bin/near'
  ]
}

vs just the last bit. If this is the expected output then I'll definitely switch, but it seems pretty noisy to me.

[volovyks]

@volovyk-s. If I throw the error I get

near repl

launch interactive Node.js shell with NEAR connection available to use.
The repl's initial context contains `nearAPI`, `near` and `account`
if an accountId cli argument is provided.
To load a script into the repl use  ".load script.js".

Use the the 'script' option to pass context to a provided
javascript/typescript file which exports a main function.
Arguments after "--" are passed to script

USAGE:
    near repl --accountId bob
    > console.log(account)
    > .load script.js

    near repl -s ./scripts/delpoyContracts.js
    near repl -s ./scripts/run.js -- test.near bob.test.near
    near repl -s ./script.ts


Options:
      --help                     Show help  [boolean]
      --version                  Show version number  [boolean]
      --nodeUrl, --node_url      NEAR node URL  [string] [default: "https://rpc.testnet.near.org"]
      --networkId, --network_id  NEAR network ID, allows using different keys based on network  [string] [default: "testnet"]
      --helperUrl                NEAR contract helper URL  [string]
      --keyPath                  Path to master account key  [string]
      --accountId, --account_id  Unique identifier for the account  [string]
      --useLedgerKey             Use Ledger for signing with given HD key path  [string] [default: "44'/397'/0'/0'/1'"]
      --seedPhrase               Seed phrase mnemonic  [string]
      --seedPath                 HD path derivation  [string] [default: "m/44'/397'/0'"]
      --walletUrl                Website for NEAR Wallet  [string]
      --contractName             Account name of contract  [string]
      --masterAccount            Master account used when creating new accounts  [string]
      --helperAccount            Expected top-level account for a network  [string]
  -v, --verbose                  Prints out verbose output  [boolean] [default: false]
  -f, --force                    Forcefully execute the desired action even if it is unsafe to do so  [boolean] [default: false]
  -s, --script                   'repl': Path to a JS/TS file which exports an async function `main`,
                                 which takes a `context` object.  [string]

Error: Cannot find module '/Users/willem/c/near-cli/test/script_tet'
Require stack:
- /Users/willem/c/near-cli/commands/repl.js
- /Users/willem/c/near-cli/bin/near-cli.js
- /Users/willem/c/near-cli/bin/near
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:885:15)
    at Function.Module._load (internal/modules/cjs/loader.js:730:27)
    at Module.require (internal/modules/cjs/loader.js:957:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at loadScript (/Users/willem/c/near-cli/commands/repl.js:68:16)
    at Object.handler (/Users/willem/c/near-cli/commands/repl.js:39:34)
    at processTicksAndRejections (internal/process/task_queues.js:95:5) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/Users/willem/c/near-cli/commands/repl.js',
    '/Users/willem/c/near-cli/bin/near-cli.js',
    '/Users/willem/c/near-cli/bin/near'
  ]
}

vs just the last bit. If this is the expected output then I'll definitely switch, but it seems pretty noisy to me.

Yes, it's noisy, but I would rather be consistent and optimize it at some point.

[willemneal]

@volovyk-s Done!

[willemneal]

@volovyk-s Any other blockers?

[volovyks]

@willemneal reviewed and tested, really cool feature. The only thing that I would add is an example or description of how users expected to use it. For example, I have built this simple script:

import { Context } from "../context";

export async function main({ account, near, nearAPI, argv }: Context) {
    const state = await account.state();
    console.log(state.storage_usage);
}

And it workes fine, but only because I created this script inside of the near-cli project folder. If users need to create a project and have near-cli in their dependencies - we need to specify it in README.

[willemneal]

Ah great point! I wonder if you can access the type globally. I'll give it a try and otherwise will add the documentation. My only fear is that the global install could differ from the local one, but I don't think these types will change that much. That is unless we change NAJ significantly.

[willemneal]

@volovyk-s Couldn't figure it out and perhaps if the version mismatch is an issue we can have the global installation check the local version and complain.

So for now I added info to the README.md

[volovyks]

Got it, I'm wondering if there is a way to write such scripts as a single .js file. We can drop TS support, imports, and main function if needed.
If users need to create projects and import near-cli - we are not that far from importing naj and doing it all from scratch.

[willemneal]

The ts is optional. In fact the types import is optional since it could be typed any or typed with naj.

With js no imports are required since naj is passed. See the test js file.

Regardless this is still a leg up on Naj since you have your local keystore, can use a ledger, and get an accpunt already set up.

Scripts with just naj and no cli are hacky and fragile.

[willemneal]

Would it make sense to move the Context type to Naj?

[willemneal]

Oh misread your comment when I first read it. I think that main function is needed and what a script will end up using since top level async support is not standard.

[willemneal]

@volovyk-s Thoughts?

[willemneal]

@volovyk-s ^

[volovyks]

Sorry for the delay, @willemneal . CLI is on hold for now. Good point ^. I will merge it, maybe will add some tweaks later. Thank you once more for your contribution, this is an important feature.