Merge pull request #1437 from polywrap/pileks/feat/cli-wrapper-envs-o…

…ption

CLI - Add `--wrapper-envs` option to `build`, `codegen`, `docgen` and `test`

packages/cli/README.md

@@ -79,6 +79,9 @@ This outputs the project's ABI schema (Wasm and Interface) and binary package (W
 - `-c, --client-config <config-path>`
   Use a custom Polywrap Client configuration.
 
+- `--wrapper-envs <envs-path>`
+  Configure wrapper environment values using the provided file.
+
 - `-n, --no-codegen`
   Don't perform codegen before building.
   By default, `build` performs a `codegen` step before building your Project. This option skips this step. This is especially useful when you are testing manual changes to your types/bindings.
@@ -119,6 +122,9 @@ This command generates types and bindings for your project based on your project
 - `-c, --client-config <config-path>`
   Use a custom Polywrap Client configuration.
 
+- `--wrapper-envs <envs-path>`
+  Configure wrapper environment values using the provided file.
+
 #### Special note
 
 When running `codegen` for Plugin Projects, the Polywrap CLI will also output an ABI schema for your plugin into the `./build` directory. You can override this output directory by specifying `-p, --publish-dir <path>`.
@@ -269,6 +275,9 @@ polywrap test [options]
 - `-c, --client-config <config-path>`
   Use a custom Polywrap Client configuration.
 
+- `--wrapper-envs <envs-path>`
+  Configure wrapper environment values using the provided file.
+
 - `-o, --output-file <output-file-path>`
   Specify the output file path for the workflow result
 
@@ -426,6 +435,9 @@ polywrap docgen <action>
 - `-c, --client-config <config-path>`
   Use a custom Polywrap Client configuration.
 
+- `--wrapper-envs <envs-path>`
+  Configure wrapper environment values using the provided file.
+
 - `-i, --imports`
   Generate docs for your project's dependencies as well.
 
@@ -515,6 +527,36 @@ export function getClientConfig(
 ): Partial<PolywrapClientConfig>
 ```
 
+### The `--wrapper-envs` option
+All commands which support the `-c, --client-config` option also support the `--wrapper-envs <envs-path>` option.
+This option allows the user to set environment values for Wrappers using a simple YAML or JSON file.
+
+For example, if you would like to change the API key used within the Ethereum plugin wrapper, you can create a `envs.yaml` file:
+
+```yaml
+ens/ethereum.polywrap.eth:
+  connection:
+    node: https://mainnet.infura.io/v3/YOUR_API_KEY # Use Infura with your API key
+    networkNameOrChainId: mainnet
+```
+
+You can then run the `build`, `codegen`, `docgen` and `test` and specify your custom `--wrapper-envs`:
+
+```bash
+polywrap codegen --wrapper-envs envs.yaml
+```
+
+You can also pass environment variables into the wrappper-envs file by using `$`:
+
+```yaml
+ens/ethereum.polywrap.eth:
+  connection:
+    node: $MY_INFURA_NODE # Use environment variable called MY_INFURA_NODE
+    networkNameOrChainId: mainnet
+```
+
+If you need to use the `$` sign within your wrapper-envs file, you can escape it using `$$`.
+
 ## Logging
 
 By default, the Polywrap CLI outputs all of its messages to the console.

packages/cli/lang/en.json

@@ -1,6 +1,8 @@
 {
   "commands_common_options_configPath": "config-path",
+  "commands_common_options_wrapperEnvsPath": "envs-path",
   "commands_common_options_config": "Add custom configuration to the PolywrapClient",
+  "commands_common_options_wrapperEnvs": "Path to a JSON file containing wrapper envs",
   "commands_common_options_verbose": "Verbose output (default: false)",
   "commands_common_options_quiet": "Suppress output (default: false)",
   "commands_build_description": "Build Polywrap Projects (type: interface, wasm)",

packages/cli/lang/es.json

@@ -1,6 +1,8 @@
 {
   "commands_common_options_configPath": "config-path",
+  "commands_common_options_wrapperEnvsPath": "envs-path",
   "commands_common_options_config": "Add custom configuration to the PolywrapClient",
+  "commands_common_options_wrapperEnvs": "Path to a JSON file containing wrapper envs",
   "commands_common_options_verbose": "Verbose output (default: false)",
   "commands_common_options_quiet": "Suppress output (default: false)",
   "commands_build_description": "Build Polywrap Projects (type: interface, wasm)",

packages/cli/src/__tests__/e2e/build.spec.ts

@@ -17,6 +17,8 @@ Options:
                                      (default: ./build)
   -c, --client-config <config-path>  Add custom configuration to the
                                      PolywrapClient
+  --wrapper-envs <envs-path>         Path to a JSON file containing wrapper
+                                     envs
   -n, --no-codegen                   Skip code generation
   -s, --strategy <strategy>          Strategy to use for building the wrapper
                                      (default: "vm")

packages/cli/src/__tests__/e2e/codegen.spec.ts

@@ -22,6 +22,8 @@ Options:
                                      (JavaScript | TypeScript)
   -c, --client-config <config-path>  Add custom configuration to the
                                      PolywrapClient
+  --wrapper-envs <envs-path>         Path to a JSON file containing wrapper
+                                     envs
   -v, --verbose                      Verbose output (default: false)
   -q, --quiet                        Suppress output (default: false)
   -l, --log-file [path]              Log file to save console output to

packages/cli/src/__tests__/e2e/docgen.spec.ts

@@ -26,6 +26,8 @@ Options:
                                      (default: ./docs)
   -c, --client-config <config-path>  Add custom configuration to the
                                      PolywrapClient
+  --wrapper-envs <envs-path>         Path to a JSON file containing wrapper
+                                     envs
   -i, --imports                      Also generate docs for dependencies
   -v, --verbose                      Verbose output (default: false)
   -q, --quiet                        Suppress output (default: false)

packages/cli/src/__tests__/e2e/test.spec.ts

@@ -19,6 +19,8 @@ Options:
                                         polywrap.test.yml)
   -c, --client-config <config-path>     Add custom configuration to the
                                         PolywrapClient
+  --wrapper-envs <envs-path>            Path to a JSON file containing wrapper
+                                        envs
   -o, --output-file <output-file-path>  Output file path for the test result
   -j, --jobs <jobs...>                  Specify ids of jobs that you want to
                                         run

packages/cli/src/__tests__/unit/option-parsers/option-parsers.spec.ts

@@ -0,0 +1,64 @@
+import { Uri } from "@polywrap/core-js";
+import path from "path";
+import { parseWrapperEnvsOption } from "../../../lib";
+
+describe("unit tests for option-parsers", () => {
+  describe("wrapper-envs", () => {
+    const sampleFileEnvs = [
+      {
+        uri: Uri.from("wrap://ens/hello-world.polywrap.eth"),
+        env: {
+          foo: "bar",
+        },
+      },
+      {
+        uri: Uri.from("ens/ethereum.polywrap.eth"),
+        env: {
+          connection: {
+            node: "https://mainnet.infura.io/v3/some_api_key",
+            networkNameOrChainId: "mainnet",
+          },
+        },
+      },
+    ];
+
+    it("Should return undefined when no filename is provided", async () => {
+      const envs = await parseWrapperEnvsOption(undefined);
+
+      expect(envs).toBeUndefined();
+    });
+
+    it("Should throw for a nonexistent wrapper-env file", async () => {
+      const nonExistentFilePath = path.join(
+        __dirname,
+        "./samples/nonexistent.json"
+      );
+
+      await expect(async () => {
+        await parseWrapperEnvsOption(nonExistentFilePath);
+      }).rejects.toThrow();
+    });
+
+    it("Should return envs for a valid json file", async () => {
+      const wrapperEnvsFilePath = path.join(
+        __dirname,
+        "./samples/wrapper-envs.json"
+      );
+
+      const envs = await parseWrapperEnvsOption(wrapperEnvsFilePath);
+
+      expect(envs).toEqual(sampleFileEnvs);
+    });
+
+    it("Should return envs for a valid yaml file", async () => {
+      const wrapperEnvsFilePath = path.join(
+        __dirname,
+        "./samples/wrapper-envs.yaml"
+      );
+
+      const envs = await parseWrapperEnvsOption(wrapperEnvsFilePath);
+
+      expect(envs).toEqual(sampleFileEnvs);
+    });
+  });
+});

packages/cli/src/__tests__/unit/option-parsers/samples/wrapper-envs.json

@@ -0,0 +1,11 @@
+{
+  "ens/hello-world.polywrap.eth": {
+    "foo": "bar"
+  },
+  "ens/ethereum.polywrap.eth": {
+    "connection": {
+      "node": "https://mainnet.infura.io/v3/some_api_key",
+      "networkNameOrChainId": "mainnet"
+    }
+  }
+}

packages/cli/src/__tests__/unit/option-parsers/samples/wrapper-envs.yaml

@@ -0,0 +1,6 @@
+ens/hello-world.polywrap.eth:
+  foo: bar
+ens/ethereum.polywrap.eth:
+  connection:
+    node: https://mainnet.infura.io/v3/some_api_key
+    networkNameOrChainId: mainnet

packages/cli/src/commands/build.ts

@@ -13,6 +13,7 @@ import {
   parseClientConfigOption,
   parseManifestFileOption,
   parseLogFileOption,
+  parseWrapperEnvsOption,
 } from "../lib";
 import { CodeGenerator } from "../lib/codegen";
 import {
@@ -25,7 +26,7 @@ import {
 
 import path from "path";
 import readline from "readline";
-import { PolywrapClient } from "@polywrap/client-js";
+import { Env, PolywrapClient } from "@polywrap/client-js";
 import { PolywrapManifest } from "@polywrap/polywrap-manifest-types-js";
 import { IClientConfigBuilder } from "@polywrap/client-config-builder-js";
 
@@ -39,6 +40,7 @@ type BuildCommandOptions = {
   manifestFile: string;
   outputDir: string;
   configBuilder: IClientConfigBuilder;
+  wrapperEnvs: Env[];
   codegen: boolean; // defaults to true
   watch?: boolean;
   strategy: SupportedStrategies;
@@ -69,6 +71,10 @@ export const build: Command = {
         `-c, --client-config <${intlMsg.commands_common_options_configPath()}>`,
         `${intlMsg.commands_common_options_config()}`
       )
+      .option(
+        `--wrapper-envs <${intlMsg.commands_common_options_wrapperEnvsPath()}>`,
+        `${intlMsg.commands_common_options_wrapperEnvs()}`
+      )
       .option(`-n, --no-codegen`, `${intlMsg.commands_build_options_n()}`)
       .option(
         `-s, --strategy <${strategyStr}>`,
@@ -90,6 +96,7 @@ export const build: Command = {
             defaultPolywrapManifest
           ),
           configBuilder: await parseClientConfigOption(options.clientConfig),
+          wrapperEnvs: await parseWrapperEnvsOption(options.wrapperEnvs),
           outputDir: parseDirOption(options.outputDir, defaultOutputDir),
           strategy: options.strategy,
           logFile: parseLogFileOption(options.logFile),
@@ -139,6 +146,7 @@ async function run(options: BuildCommandOptions) {
     manifestFile,
     outputDir,
     configBuilder,
+    wrapperEnvs,
     strategy,
     codegen,
     verbose,
@@ -147,6 +155,10 @@ async function run(options: BuildCommandOptions) {
   } = options;
   const logger = createLogger({ verbose, quiet, logFile });
 
+  if (wrapperEnvs) {
+    configBuilder.addEnvs(wrapperEnvs);
+  }
+
   // Get Client
   const client = new PolywrapClient(configBuilder.buildCoreConfig(), {
     noDefaults: true,

packages/cli/src/commands/codegen.ts

@@ -15,10 +15,11 @@ import {
   defaultProjectManifestFiles,
   defaultPolywrapManifest,
   parseLogFileOption,
+  parseWrapperEnvsOption,
 } from "../lib";
 import { ScriptCodegenerator } from "../lib/codegen/ScriptCodeGenerator";
 
-import { PolywrapClient } from "@polywrap/client-js";
+import { Env, PolywrapClient } from "@polywrap/client-js";
 import path from "path";
 import fs from "fs";
 import { IClientConfigBuilder } from "@polywrap/client-config-builder-js";
@@ -35,6 +36,7 @@ type CodegenCommandOptions = {
   publishDir: string;
   script?: string;
   configBuilder: IClientConfigBuilder;
+  wrapperEnvs: Env[];
   verbose?: boolean;
   quiet?: boolean;
   logFile?: string;
@@ -72,6 +74,10 @@ export const codegen: Command = {
         `-c, --client-config <${intlMsg.commands_common_options_configPath()}>`,
         `${intlMsg.commands_common_options_config()}`
       )
+      .option(
+        `--wrapper-envs <${intlMsg.commands_common_options_wrapperEnvsPath()}>`,
+        `${intlMsg.commands_common_options_wrapperEnvs()}`
+      )
       .option("-v, --verbose", intlMsg.commands_common_options_verbose())
       .option("-q, --quiet", intlMsg.commands_common_options_quiet())
       .option(
@@ -82,6 +88,7 @@ export const codegen: Command = {
         await run({
           ...options,
           configBuilder: await parseClientConfigOption(options.clientConfig),
+          wrapperEnvs: await parseWrapperEnvsOption(options.wrapperEnvs),
           codegenDir: parseDirOption(options.codegenDir, defaultCodegenDir),
           script: parseCodegenScriptOption(options.script),
           manifestFile: parseManifestFileOption(
@@ -101,13 +108,18 @@ async function run(options: CodegenCommandOptions) {
     codegenDir,
     script,
     configBuilder,
+    wrapperEnvs,
     publishDir,
     verbose,
     quiet,
     logFile,
   } = options;
   const logger = createLogger({ verbose, quiet, logFile });
 
+  if (wrapperEnvs) {
+    configBuilder.addEnvs(wrapperEnvs);
+  }
+
   // Get Client
   const client = new PolywrapClient(configBuilder.buildCoreConfig(), {
     noDefaults: true,

packages/cli/src/commands/docgen.ts

@@ -9,6 +9,7 @@ import {
   defaultProjectManifestFiles,
   getProjectFromManifest,
   parseLogFileOption,
+  parseWrapperEnvsOption,
 } from "../lib";
 import { Command, Program } from "./types";
 import { createLogger } from "./utils/createLogger";
@@ -17,7 +18,7 @@ import { scriptPath as jsdocScriptPath } from "../lib/docgen/jsdoc";
 import { scriptPath as schemaScriptPath } from "../lib/docgen/schema";
 import { ScriptCodegenerator } from "../lib/codegen/ScriptCodeGenerator";
 
-import { PolywrapClient } from "@polywrap/client-js";
+import { Env, PolywrapClient } from "@polywrap/client-js";
 import chalk from "chalk";
 import { Argument } from "commander";
 import { IClientConfigBuilder } from "@polywrap/client-config-builder-js";
@@ -37,6 +38,7 @@ type DocgenCommandOptions = {
   manifestFile: string;
   docgenDir: string;
   configBuilder: IClientConfigBuilder;
+  wrapperEnvs: Env[];
   imports: boolean;
   verbose?: boolean;
   quiet?: boolean;
@@ -93,6 +95,10 @@ export const docgen: Command = {
         `-c, --client-config <${intlMsg.commands_common_options_configPath()}>`,
         `${intlMsg.commands_common_options_config()}`
       )
+      .option(
+        `--wrapper-envs <${intlMsg.commands_common_options_wrapperEnvsPath()}>`,
+        `${intlMsg.commands_common_options_wrapperEnvs()}`
+      )
       .option(`-i, --imports`, `${intlMsg.commands_docgen_options_i()}`)
       .option("-v, --verbose", intlMsg.commands_common_options_verbose())
       .option("-q, --quiet", intlMsg.commands_common_options_quiet())
@@ -109,6 +115,7 @@ export const docgen: Command = {
           ),
           docgenDir: parseDirOption(options.docgenDir, defaultDocgenDir),
           configBuilder: await parseClientConfigOption(options.clientConfig),
+          wrapperEnvs: await parseWrapperEnvsOption(options.wrapperEnvs),
           logFile: parseLogFileOption(options.logFile),
         });
       });
@@ -120,13 +127,18 @@ async function run(command: DocType, options: DocgenCommandOptions) {
     manifestFile,
     docgenDir,
     configBuilder,
+    wrapperEnvs,
     imports,
     verbose,
     quiet,
     logFile,
   } = options;
   const logger = createLogger({ verbose, quiet, logFile });
 
+  if (wrapperEnvs) {
+    configBuilder.addEnvs(wrapperEnvs);
+  }
+
   let project = await getProjectFromManifest(manifestFile, logger);
 
   if (!project) {