agoric 0.21.2-upgrade-18-dev-6ddbef0.0 → 0.21.2-upgrade-19-dev-ae3bcff.0

package/src/commands/oracle.js

@@ -1,19 +1,23 @@
 // @ts-check
 /* eslint-disable func-names */
 /* eslint-env node */
+import {
+  fetchEnvNetworkConfig,
+  makeAgoricNames,
+  makeVstorageKit,
+  makeWalletUtils,
+  storageHelper,
+} from '@agoric/client-utils';
 import { Offers } from '@agoric/inter-protocol/src/clientSupport.js';
 import { oracleBrandFeedName } from '@agoric/inter-protocol/src/proposals/utils.js';
 import { Fail } from '@endo/errors';
 import { Nat } from '@endo/nat';
-import * as cp from 'child_process';
 import { Command } from 'commander';
 import { inspect } from 'util';
 import { normalizeAddressWithOptions } from '../lib/chain.js';
 import { bigintReplacer } from '../lib/format.js';
-import { getNetworkConfig, makeRpcUtils, storageHelper } from '../lib/rpc.js';
 import {
   getCurrent,
-  makeWalletUtils,
   outputAction,
   sendAction,
   sendHint,
@@ -23,26 +27,33 @@ import {
 
 // XXX support other decimal places
 const COSMOS_UNIT = 1_000_000n;
-const scaleDecimals = num => BigInt(num * Number(COSMOS_UNIT));
+/** @param {number} num */
+const scaleDecimals = num => BigInt(Math.round(num * Number(COSMOS_UNIT)));
 
 /**
  * Prints JSON output to stdout and diagnostic info (like logs) to stderr
  *
- * @param {import('anylogger').Logger} logger
  * @param {{
- *   delay?: (ms: number) => Promise<void>,
- *   execFileSync?: typeof import('child_process').execFileSync,
- *   env?: Record<string, string | undefined>,
- *   stdout?: Pick<import('stream').Writable,'write'>,
- * }} [io]
+ *   createCommand: typeof import('commander').createCommand,
+ *   env: Partial<Record<string, string>>,
+ *   execFileSync: typeof import('child_process').execFileSync,
+ *   now: () => number,
+ *   setTimeout: typeof setTimeout,
+ *   stderr: Pick<import('stream').Writable,'write'>,
+ *   stdout: Pick<import('stream').Writable,'write'>,
+ * }} process
+ * @param {import('anylogger').Logger} [logger]
  */
-export const makeOracleCommand = (logger, io = {}) => {
-  const {
-    delay = ms => new Promise(resolve => setTimeout(resolve, ms)),
-    execFileSync = cp.execFileSync,
-    env = process.env,
-    stdout = process.stdout,
-  } = io;
+export const makeOracleCommand = (
+  { env, execFileSync, setTimeout, stderr, stdout },
+  logger,
+) => {
+  /**
+   * @param {number} ms
+   * @returns {Promise<void>}
+   */
+  const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
   const oracle = new Command('oracle')
     .description('Oracle commands')
     .usage(
@@ -82,20 +93,24 @@ export const makeOracleCommand = (logger, io = {}) => {
 
   const rpcTools = async () => {
     // XXX pass fetch to getNetworkConfig() explicitly
-    const networkConfig = await getNetworkConfig(env);
-    const utils = await makeRpcUtils({ fetch });
+    const networkConfig = await fetchEnvNetworkConfig({
+      env: process.env,
+      fetch,
+    });
+    const vsk = makeVstorageKit({ fetch }, networkConfig);
+    const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
     const lookupPriceAggregatorInstance = ([brandIn, brandOut]) => {
       const name = oracleBrandFeedName(brandIn, brandOut);
-      const instance = utils.agoricNames.instance[name];
+      const instance = agoricNames.instance[name];
       if (!instance) {
-        logger.debug('known instances:', utils.agoricNames.instance);
+        logger && logger.debug('known instances:', agoricNames.instance);
         throw Error(`Unknown instance ${name}`);
       }
       return instance;
     };
 
-    return { ...utils, networkConfig, lookupPriceAggregatorInstance };
+    return { ...vsk, networkConfig, lookupPriceAggregatorInstance };
   };
 
   oracle
@@ -128,12 +143,15 @@ export const makeOracleCommand = (logger, io = {}) => {
         proposal: {},
       };
 
-      outputAction({
-        method: 'executeOffer',
-        offer,
-      });
+      outputAction(
+        {
+          method: 'executeOffer',
+          offer,
+        },
+        stdout,
+      );
 
-      console.warn(sendHint);
+      stderr.write(sendHint);
     });
 
   oracle
@@ -163,16 +181,19 @@ export const makeOracleCommand = (logger, io = {}) => {
         opts.oracleAdminAcceptOfferId,
       );
 
-      outputAction({
-        method: 'executeOffer',
-        offer,
-      });
+      outputAction(
+        {
+          method: 'executeOffer',
+          offer,
+        },
+        stdout,
+      );
 
-      console.warn(sendHint);
+      stderr.write(sendHint);
     });
 
-  const findOracleCap = async (instance, from, readLatestHead) => {
-    const current = await getCurrent(from, { readLatestHead });
+  const findOracleCap = async (instance, from, readPublished) => {
+    const current = await getCurrent(from, { readPublished });
 
     const { offerToUsedInvitation: entries } = /** @type {any} */ (current);
     Array.isArray(entries) || Fail`entries must be an array: ${entries}`;
@@ -200,11 +221,10 @@ export const makeOracleCommand = (logger, io = {}) => {
       s => s.split('.'),
     )
     .action(async opts => {
-      const { readLatestHead, lookupPriceAggregatorInstance } =
-        await rpcTools();
+      const { readPublished, lookupPriceAggregatorInstance } = await rpcTools();
       const instance = lookupPriceAggregatorInstance(opts.pair);
 
-      const offerId = await findOracleCap(instance, opts.from, readLatestHead);
+      const offerId = await findOracleCap(instance, opts.from, readPublished);
       if (!offerId) {
         console.error('No continuing ids found');
       }
@@ -265,12 +285,13 @@ export const makeOracleCommand = (logger, io = {}) => {
          * }}
          */ { pair, keys, price },
       ) => {
-        const { readLatestHead, networkConfig, lookupPriceAggregatorInstance } =
-          await rpcTools();
-        const wutil = await makeWalletUtils(
-          { fetch, execFileSync, delay },
+        const {
+          readLatestHead,
+          readPublished,
           networkConfig,
-        );
+          lookupPriceAggregatorInstance,
+        } = await rpcTools();
+        const wutil = await makeWalletUtils({ fetch, delay }, networkConfig);
         const unitPrice = scaleDecimals(price);
 
         const feedPath = `published.priceFeed.${pair[0]}-${pair[1]}_price_feed`;
@@ -279,7 +300,7 @@ export const makeOracleCommand = (logger, io = {}) => {
           /** @type {Promise<PriceDescription>} */ (
             readLatestHead(feedPath).catch(() => {
               const viewer = `https://vstorage.agoric.net/#${networkConfig.rpcAddrs[0]}|published,published.priceFeed|${feedPath}`;
-              console.warn(`no existing price data; see ${viewer}`);
+              stderr.write(`no existing price data; see ${viewer}`);
               return undefined;
             })
           );
@@ -324,7 +345,7 @@ export const makeOracleCommand = (logger, io = {}) => {
               }
             }),
           ]).catch(err => {
-            console.warn(err);
+            stderr.write(err);
           });
         }
 
@@ -334,7 +355,7 @@ export const makeOracleCommand = (logger, io = {}) => {
           adminOfferIds[from] = await findOracleCap(
             instance,
             from,
-            readLatestHead,
+            readPublished,
           );
           if (!adminOfferIds[from]) {
             console.error(

package/src/commands/perf.js

@@ -7,21 +7,23 @@ import {
   makeFollower,
   makeLeaderFromRpcAddresses,
 } from '@agoric/casting';
+import { fetchEnvNetworkConfig } from '@agoric/client-utils';
+import { slotToRemotable } from '@agoric/internal/src/storage-test-utils.js';
+import { boardSlottingMarshaller } from '@agoric/vats/tools/board-utils.js';
 import { Command } from 'commander';
 import fs from 'fs';
 import { exit } from 'process';
-import { slotToRemotable } from '@agoric/internal/src/storage-test-utils.js';
-import { boardSlottingMarshaller } from '@agoric/vats/tools/board-utils.js';
 import { makeLeaderOptions } from '../lib/casting.js';
 import {
   execSwingsetTransaction,
   normalizeAddressWithOptions,
 } from '../lib/chain.js';
-import { networkConfig } from '../lib/rpc.js';
 
 // tight for perf testing but less than this tends to hang.
 const SLEEP_SECONDS = 0.1;
 
+const networkConfig = await fetchEnvNetworkConfig({ env: process.env, fetch });
+
 /**
  * @param {import('anylogger').Logger} logger
  */

package/src/commands/psm.js

@@ -1,12 +1,19 @@
 // @ts-check
 /* eslint-disable func-names */
 /* eslint-env node */
-import { Command } from 'commander';
+import {
+  fetchEnvNetworkConfig,
+  makeAgoricNames,
+  makeVstorageKit,
+  storageHelper,
+} from '@agoric/client-utils';
 import { Offers } from '@agoric/inter-protocol/src/clientSupport.js';
+import { Command } from 'commander';
 import { asPercent } from '../lib/format.js';
-import { makeRpcUtils, storageHelper } from '../lib/rpc.js';
 import { outputExecuteOfferAction } from '../lib/wallet.js';
 
+const networkConfig = await fetchEnvNetworkConfig({ env: process.env, fetch });
+
 // Adapted from https://gist.github.com/dckc/8b5b2f16395cb4d7f2ff340e0bc6b610#file-psm-tool
 
 /**
@@ -60,13 +67,14 @@ export const makePsmCommand = logger => {
   );
 
   const rpcTools = async () => {
-    const utils = await makeRpcUtils({ fetch });
+    const vsk = await makeVstorageKit({ fetch }, networkConfig);
+    const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
     const lookupPsmInstance = ([minted, anchor]) => {
       const name = `psm-${minted}-${anchor}`;
-      const instance = utils.agoricNames.instance[name];
+      const instance = agoricNames.instance[name];
       if (!instance) {
-        logger.debug('known instances:', utils.agoricNames.instance);
+        logger.debug('known instances:', agoricNames.instance);
         throw Error(`Unknown instance ${name}`);
       }
       return instance;
@@ -77,20 +85,19 @@ export const makePsmCommand = logger => {
      * @param {[Minted: string, Anchor: string]} pair
      */
     const getGovernanceState = async ([Minted, Anchor]) => {
-      const govContent = await utils.vstorage.readLatest(
+      const govContent = await vsk.vstorage.readLatest(
         `published.psm.${Minted}.${Anchor}.governance`,
       );
       assert(govContent, 'no gov content');
       const { current: governance } = last(
-        storageHelper.unserializeTxt(govContent, utils.fromBoard),
+        storageHelper.unserializeTxt(govContent, vsk.fromBoard),
       );
-      const { [`psm.${Minted}.${Anchor}`]: instance } =
-        utils.agoricNames.instance;
+      const { [`psm.${Minted}.${Anchor}`]: instance } = agoricNames.instance;
 
       return { instance, governance };
     };
 
-    return { ...utils, lookupPsmInstance, getGovernanceState };
+    return { ...vsk, agoricNames, lookupPsmInstance, getGovernanceState };
   };
 
   psm

package/src/commands/reserve.js

@@ -1,11 +1,17 @@
 // @ts-check
 /* eslint-disable func-names */
 /* eslint-env node */
+import {
+  fetchEnvNetworkConfig,
+  makeAgoricNames,
+  makeVstorageKit,
+} from '@agoric/client-utils';
 import { Offers } from '@agoric/inter-protocol/src/clientSupport.js';
 import { Command } from 'commander';
-import { makeRpcUtils } from '../lib/rpc.js';
 import { outputActionAndHint } from '../lib/wallet.js';
 
+const networkConfig = await fetchEnvNetworkConfig({ env: process.env, fetch });
+
 /**
  * @param {import('anylogger').Logger} _logger
  * @param {*} io
@@ -29,7 +35,8 @@ export const makeReserveCommand = (_logger, io = {}) => {
        * }} opts
        */
       async ({ collateralBrand, ...opts }) => {
-        const { agoricNames } = await makeRpcUtils({ fetch });
+        const vsk = makeVstorageKit({ fetch }, networkConfig);
+        const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
         const offer = Offers.reserve.AddCollateral(agoricNames, {
           collateralBrandKey: collateralBrand,
@@ -63,7 +70,8 @@ export const makeReserveCommand = (_logger, io = {}) => {
       1,
     )
     .action(async function (opts) {
-      const { agoricNames } = await makeRpcUtils({ fetch });
+      const vsk = makeVstorageKit({ fetch }, networkConfig);
+      const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
       const reserveInstance = agoricNames.instance.reserve;
       assert(reserveInstance, 'missing reserve in names');

package/src/commands/test-upgrade.js

@@ -1,11 +1,11 @@
 // @ts-check
 /* eslint-env node */
+import { fetchEnvNetworkConfig, makeWalletUtils } from '@agoric/client-utils';
 import { Fail } from '@endo/errors';
 import { CommanderError } from 'commander';
 import { normalizeAddressWithOptions } from '../lib/chain.js';
 import { bigintReplacer } from '../lib/format.js';
-import { getNetworkConfig } from '../lib/rpc.js';
-import { makeWalletUtils, sendAction } from '../lib/wallet.js';
+import { sendAction } from '../lib/wallet.js';
 
 /**
  * Make commands for testing.
@@ -38,8 +38,8 @@ export const makeTestCommand = (
     try {
       // XXX pass fetch to getNetworkConfig() explicitly
       // await null above makes this await safe
-      const networkConfig = await getNetworkConfig(env);
-      return makeWalletUtils({ fetch, execFileSync, delay }, networkConfig);
+      const networkConfig = await fetchEnvNetworkConfig({ env, fetch });
+      return makeWalletUtils({ fetch, delay }, networkConfig);
     } catch (err) {
       // CommanderError is a class constructor, and so
       // must be invoked with `new`.

package/src/commands/vaults.js

@@ -1,15 +1,21 @@
 // @ts-check
 /* eslint-disable func-names */
 /* eslint-env node */
-import { Command } from 'commander';
+import {
+  fetchEnvNetworkConfig,
+  makeAgoricNames,
+  makeVstorageKit,
+} from '@agoric/client-utils';
 import {
   lookupOfferIdForVault,
   Offers,
 } from '@agoric/inter-protocol/src/clientSupport.js';
+import { Command } from 'commander';
 import { normalizeAddressWithOptions } from '../lib/chain.js';
-import { makeRpcUtils } from '../lib/rpc.js';
 import { getCurrent, outputExecuteOfferAction } from '../lib/wallet.js';
 
+const networkConfig = await fetchEnvNetworkConfig({ env: process.env, fetch });
+
 /**
  * @param {import('anylogger').Logger} logger
  */
@@ -36,10 +42,10 @@ export const makeVaultsCommand = logger => {
       normalizeAddress,
     )
     .action(async function (opts) {
-      const { readLatestHead } = await makeRpcUtils({ fetch });
+      const { readPublished } = await makeVstorageKit({ fetch }, networkConfig);
 
       const current = await getCurrent(opts.from, {
-        readLatestHead,
+        readPublished,
       });
 
       const vaultStoragePaths = current.offerToPublicSubscriberPaths.map(
@@ -61,7 +67,8 @@ export const makeVaultsCommand = logger => {
     .option('--collateralBrand <string>', 'Collateral brand key', 'ATOM')
     .action(async function (opts) {
       logger.warn('running with options', opts);
-      const { agoricNames } = await makeRpcUtils({ fetch });
+      const vsk = makeVstorageKit({ fetch }, networkConfig);
+      const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
       const offer = Offers.vaults.OpenVault(agoricNames, {
         giveCollateral: opts.giveCollateral,
@@ -96,11 +103,15 @@ export const makeVaultsCommand = logger => {
     .requiredOption('--vaultId <string>', 'Key of vault (e.g. vault1)')
     .action(async function (opts) {
       logger.warn('running with options', opts);
-      const { agoricNames, readLatestHead } = await makeRpcUtils({ fetch });
+      const { readPublished, ...vsk } = makeVstorageKit(
+        { fetch },
+        networkConfig,
+      );
+      const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
       const previousOfferId = await lookupOfferIdForVault(
         opts.vaultId,
-        getCurrent(opts.from, { readLatestHead }),
+        getCurrent(opts.from, { readPublished }),
       );
 
       const offer = Offers.vaults.AdjustBalances(
@@ -137,11 +148,15 @@ export const makeVaultsCommand = logger => {
     )
     .action(async function (opts) {
       logger.warn('running with options', opts);
-      const { agoricNames, readLatestHead } = await makeRpcUtils({ fetch });
+      const { readPublished, ...vsk } = makeVstorageKit(
+        { fetch },
+        networkConfig,
+      );
+      const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
       const previousOfferId = await lookupOfferIdForVault(
         opts.vaultId,
-        getCurrent(opts.from, { readLatestHead }),
+        getCurrent(opts.from, { readPublished }),
       );
 
       const offer = Offers.vaults.CloseVault(

package/src/commands/wallet.js

@@ -8,11 +8,14 @@ import {
   makeLeader,
   makeLeaderFromRpcAddresses,
 } from '@agoric/casting';
+import {
+  makeVstorageKit,
+  fetchEnvNetworkConfig,
+  makeAgoricNames,
+} from '@agoric/client-utils';
+import { execFileSync } from 'child_process';
 import fs from 'fs';
 import util from 'util';
-import { execFileSync } from 'child_process';
-import { fmtRecordOfLines, summarize } from '../lib/format.js';
-import { makeRpcUtils, networkConfig } from '../lib/rpc.js';
 
 import { makeLeaderOptions } from '../lib/casting.js';
 import {
@@ -20,8 +23,15 @@ import {
   fetchSwingsetParams,
   normalizeAddressWithOptions,
 } from '../lib/chain.js';
+import {
+  fmtRecordOfLines,
+  parseFiniteNumber,
+  summarize,
+} from '../lib/format.js';
 import { coalesceWalletState, getCurrent } from '../lib/wallet.js';
 
+const networkConfig = await fetchEnvNetworkConfig({ env: process.env, fetch });
+
 const SLEEP_SECONDS = 3;
 
 /**
@@ -45,6 +55,7 @@ export const makeWalletCommand = async command => {
     'wallet commands',
   );
 
+  /** @param {string} literalOrName */
   const normalizeAddress = literalOrName =>
     normalizeAddressWithOptions(literalOrName, wallet.opts());
 
@@ -102,9 +113,9 @@ export const makeWalletCommand = async command => {
     .action(async function (opts) {
       const offerStr = fs.readFileSync(opts.file).toString();
 
-      const { unserializer } = await makeRpcUtils({ fetch });
+      const { marshaller } = makeVstorageKit({ fetch }, networkConfig);
 
-      const offerObj = unserializer.fromCapData(JSON.parse(offerStr));
+      const offerObj = marshaller.fromCapData(JSON.parse(offerStr));
       console.log(offerObj);
     });
 
@@ -117,9 +128,9 @@ export const makeWalletCommand = async command => {
     .action(async function (opts) {
       const offerStr = fs.readFileSync(opts.offer).toString();
 
-      const { unserializer } = await makeRpcUtils({ fetch });
+      const { marshaller } = makeVstorageKit({ fetch }, networkConfig);
 
-      const offerObj = unserializer.fromCapData(JSON.parse(offerStr));
+      const offerObj = marshaller.fromCapData(JSON.parse(offerStr));
       console.log(offerObj.offer.id);
     });
 
@@ -132,30 +143,69 @@ export const makeWalletCommand = async command => {
     )
     .requiredOption('--offer [filename]', 'path to file with prepared offer')
     .option('--dry-run', 'spit out the command instead of running it')
+    .option('--gas', 'gas limit; "auto" [default] to calculate automatically')
+    .option(
+      '--gas-adjustment',
+      'factor by which to multiply the --gas=auto calculation result [default 1.2]',
+    )
+    .option('--verbose', 'print command output')
     .action(function (opts) {
-      /** @typedef {{ from: string, offer: string, dryRun: boolean }} Opts */
+      /**
+       * @typedef {{
+       *   from: string,
+       *   offer: string,
+       *   dryRun: boolean,
+       *   gas: string,
+       *   gasAdjustment: string,
+       *   verbose: boolean,
+       * }} Opts
+       */
       const {
         dryRun,
         from,
+        gas = 'auto',
+        gasAdjustment = '1.2',
         offer,
         home,
+        verbose,
         keyringBackend: backend,
       } = /** @type {SharedTxOptions & Opts} */ ({ ...wallet.opts(), ...opts });
 
       const offerBody = fs.readFileSync(offer).toString();
-      execSwingsetTransaction(['wallet-action', '--allow-spend', offerBody], {
-        from,
-        dryRun,
-        keyring: { home, backend },
-        ...networkConfig,
-      });
+      const out = execSwingsetTransaction(
+        ['wallet-action', '--allow-spend', offerBody, '-ojson', '-bblock'],
+        {
+          ...networkConfig,
+          keyring: { home, backend },
+          from,
+          gas:
+            gas === 'auto'
+              ? ['auto', parseFiniteNumber(gasAdjustment)]
+              : parseFiniteNumber(gas),
+          dryRun,
+          verbose,
+        },
+      );
+
+      // see sendAction in {@link ../lib/wallet.js}
+      if (dryRun || !verbose) return;
+      try {
+        const tx = JSON.parse(/** @type {string} */ (out));
+        if (tx.code !== 0) {
+          console.error('failed to send tx', tx);
+        }
+        console.log(tx);
+      } catch (err) {
+        console.error('unexpected output', JSON.stringify(out));
+        throw err;
+      }
     });
 
   wallet
     .command('list')
     .description('list all wallets in vstorage')
     .action(async function () {
-      const { vstorage } = await makeRpcUtils({ fetch });
+      const { vstorage } = makeVstorageKit({ fetch }, networkConfig);
       const wallets = await vstorage.keys('published.wallet');
       process.stdout.write(wallets.join('\n'));
     });
@@ -169,23 +219,26 @@ export const makeWalletCommand = async command => {
       normalizeAddress,
     )
     .action(async function (opts) {
-      const { agoricNames, unserializer, readLatestHead } = await makeRpcUtils({
-        fetch,
-      });
+      const {
+        readPublished,
+        marshaller: unserializer,
+        ...vsk
+      } = makeVstorageKit({ fetch }, networkConfig);
+      const agoricNames = await makeAgoricNames(vsk.fromBoard, vsk.vstorage);
 
       const leader = makeLeader(networkConfig.rpcAddrs[0]);
       const follower = await makeFollower(
         `:published.wallet.${opts.from}`,
         leader,
         {
-          // @ts-expect-error xxx
+          // @ts-expect-error xxx follower/marshaller types
           unserializer,
         },
       );
 
       const coalesced = await coalesceWalletState(follower);
 
-      const current = await getCurrent(opts.from, { readLatestHead });
+      const current = await getCurrent(opts.from, { readPublished });
 
       console.warn(
         'got coalesced',

package/src/cosmos.js

@@ -50,7 +50,7 @@ export default async function cosmosMain(progname, rawArgs, powers, opts) {
                 },
               );
               // Ensure the build doesn't mess up stdout.
-              ps.childProcess.stdout.pipe(process.stderr);
+              ps.childProcess.stdout?.pipe(process.stderr);
               return ps;
             }
             throw e;

package/src/helpers.js

@@ -3,6 +3,9 @@
 
 /** @import { ChildProcess } from 'child_process' */
 
+// Backwards compatibility
+export { fetchEnvNetworkConfig as getNetworkConfig } from '@agoric/client-utils';
+
 export const getSDKBinaries = ({
   jsPfx = '../..',
   goPfx = `${jsPfx}/../golang`,
@@ -40,12 +43,12 @@ export const makePspawn = ({
    *
    * @param {string} cmd command name to run
    * @param {Array<string>} cargs arguments to the command
-   * @param {object} param2
-   * @param {string} [param2.cwd]
-   * @param {string | [string, string, string]} [param2.stdio] standard IO
+   * @param {object} [opts]
+   * @param {string} [opts.cwd]
+   * @param {string | [string, string, string]} [opts.stdio] standard IO
    * specification
-   * @param {Record<string, string | undefined>} [param2.env] environment
-   * @param {boolean} [param2.detached] whether the child process should be detached
+   * @param {Record<string, string | undefined>} [opts.env] environment
+   * @param {boolean} [opts.detached] whether the child process should be detached
    * @returns {Promise<number> & { childProcess: ChildProcess }}} promise for
    * exit status. The return result has a `childProcess` property to obtain
    * control over the running process