@agoric/deploy-script-support 0.10.3 → 0.10.4-calypso-dev-84eb287.0

package/src/extract-proposal.js

@@ -11,21 +11,47 @@ import {
 } from './coreProposalBehavior.js';
 
 /**
- * @typedef {string | { module: string, entrypoint: string, args?: Array<unknown> }} ConfigProposal
+ * @typedef {string | {module: string, entrypoint?: string, args?: Array<unknown>}} ConfigProposal
  */
 
-const { details: X, Fail } = assert;
+/**
+ * @typedef {{steps: ConfigProposal[][]}} SequentialCoreProposals
+ * @typedef {ConfigProposal[] | SequentialCoreProposals} CoreProposals
+ */
+
+const { Fail } = assert;
 
 const req = createRequire(import.meta.url);
 
+/**
+ * @param  {...(CoreProposals | undefined | null)} args
+ * @returns {SequentialCoreProposals}
+ */
+export const mergeCoreProposals = (...args) => {
+  /** @type {ConfigProposal[][]} */
+  const steps = [];
+  for (const coreProposal of args) {
+    if (!coreProposal) {
+      continue;
+    }
+    if ('steps' in coreProposal) {
+      steps.push(...coreProposal.steps);
+    } else {
+      steps.push(coreProposal);
+    }
+  }
+  return harden({ steps });
+};
+harden(mergeCoreProposals);
+
 /**
  * @param {(ModuleSpecifier | FilePath)[]} paths
  * @typedef {string} ModuleSpecifier
  * @typedef {string} FilePath
  */
 const pathResolve = (...paths) => {
-  const fileName = paths.pop();
-  assert(fileName, '>=1 paths required');
+  const fileName = /** @type {string} */ (paths.pop());
+  fileName || Fail`base name required`;
   try {
     return req.resolve(fileName, {
       paths,
@@ -35,6 +61,24 @@ const pathResolve = (...paths) => {
   }
 };
 
+const findModule = (initDir, srcSpec) =>
+  srcSpec.match(/^(\.\.?)?\//)
+    ? pathResolve(initDir, srcSpec)
+    : req.resolve(srcSpec);
+
+/**
+ * @param {{ bundleID?: string, bundleName?: string }} handle - mutated then hardened
+ * @param {string} sourceSpec - the specifier of a module to load
+ * @param {string} key - the key of the proposal
+ * @param {string} piece - the piece of the proposal
+ * @returns {Promise<[string, any]>}
+ */
+const namedHandleToBundleSpec = async (handle, sourceSpec, key, piece) => {
+  handle.bundleName = `coreProposal${String(key)}_${piece}`;
+  harden(handle);
+  return harden([handle.bundleName, { sourceSpec }]);
+};
+
 /**
  * Format core proposals to be run at bootstrap:
  * SwingSet `bundles` configuration
@@ -46,188 +90,225 @@ const pathResolve = (...paths) => {
  * but for sim-chain and such, they can be declared statically in
  * the chain configuration, in which case they are run at bootstrap.
  *
- * @param {ConfigProposal[]} coreProposals - governance
+ * @param {CoreProposals} coreProposals - governance
  * proposals to run at chain bootstrap for scenarios such as sim-chain.
  * @param {FilePath} [dirname]
- * @param {typeof makeEnactCoreProposalsFromBundleRef} [makeEnactCoreProposals]
- * @param {(i: number) => number} [getSequenceForProposal]
+ * @param {object} [opts]
+ * @param {typeof makeEnactCoreProposalsFromBundleRef} [opts.makeEnactCoreProposals]
+ * @param {(key: PropertyKey) => PropertyKey} [opts.getSequenceForProposal]
+ * @param {typeof namedHandleToBundleSpec} [opts.handleToBundleSpec]
  */
 export const extractCoreProposalBundles = async (
   coreProposals,
   dirname = '.',
-  makeEnactCoreProposals = makeEnactCoreProposalsFromBundleRef,
-  getSequenceForProposal,
+  opts,
 ) => {
-  if (!getSequenceForProposal) {
-    // Deterministic proposal numbers.
-    getSequenceForProposal = i => i;
-  }
+  const {
+    makeEnactCoreProposals = makeEnactCoreProposalsFromBundleRef,
+    getSequenceForProposal = key => key,
+    handleToBundleSpec = namedHandleToBundleSpec,
+  } = opts || {};
 
   dirname = pathResolve(dirname);
   dirname = await fs.promises
     .stat(dirname)
     .then(stbuf => (stbuf.isDirectory() ? dirname : path.dirname(dirname)));
 
-  /** @type {Map<{ bundleName?: string }, { source: string, bundle?: string }>} */
+  /** @type {Map<{ bundleID?: string, bundleName?: string }, { source: string, bundle?: string }>} */
   const bundleHandleToAbsolutePaths = new Map();
 
+  const proposalSteps =
+    'steps' in coreProposals ? coreProposals.steps : [coreProposals];
   const bundleToSource = new Map();
-  const extracted = await Promise.all(
-    coreProposals.map(async (coreProposal, i) => {
-      // console.debug(`Parsing core proposal:`, coreProposal);
-
-      /** @type {string} */
-      let entrypoint;
-      /** @type {unknown[]} */
-      let args;
-      /** @type {string} */
-      let module;
-      if (typeof coreProposal === 'string') {
-        module = coreProposal;
-        entrypoint = 'defaultProposalBuilder';
-        args = [];
-      } else {
-        ({ module, entrypoint, args = [] } = coreProposal);
-      }
-
-      typeof module === 'string' ||
-        Fail`coreProposal module ${module} must be string`;
-      typeof entrypoint === 'string' ||
-        Fail`coreProposal entrypoint ${entrypoint} must be string`;
-      Array.isArray(args) || Fail`coreProposal args ${args} must be array`;
-
-      const thisProposalBundleHandles = new Set();
-      assert(getSequenceForProposal);
-      const thisProposalSequence = getSequenceForProposal(i);
-      const initPath = pathResolve(dirname, module);
-      const initDir = path.dirname(initPath);
-      /** @type {Record<string, import('./externalTypes.js').ProposalBuilder>} */
-      const ns = await import(initPath);
-      const install = (srcSpec, bundlePath) => {
-        const absoluteSrc = pathResolve(initDir, srcSpec);
-        const bundleHandle = {};
-        const absolutePaths = { source: absoluteSrc };
-        if (bundlePath) {
-          const absoluteBundle = pathResolve(initDir, bundlePath);
-          absolutePaths.bundle = absoluteBundle;
-          const oldSource = bundleToSource.get(absoluteBundle);
-          if (oldSource) {
-            assert.equal(
-              oldSource,
-              absoluteSrc,
-              X`${bundlePath} already installed from ${oldSource}, now ${absoluteSrc}`,
-            );
+  const extractedSteps = await Promise.all(
+    proposalSteps.map((proposalStep, i) =>
+      Promise.all(
+        proposalStep.map(async (coreProposal, j) => {
+          const key = `${i}.${j}`;
+          // console.debug(`Parsing core proposal:`, coreProposal);
+
+          /** @type {string} */
+          let entrypoint;
+          /** @type {unknown[]} */
+          let args;
+          /** @type {string} */
+          let module;
+          if (typeof coreProposal === 'string') {
+            module = coreProposal;
+            entrypoint = 'defaultProposalBuilder';
+            args = [];
           } else {
-            bundleToSource.set(absoluteBundle, absoluteSrc);
-          }
-        }
-        // Don't harden the bundleHandle since we need to set the bundleName on
-        // its unique identity later.
-        thisProposalBundleHandles.add(bundleHandle);
-        bundleHandleToAbsolutePaths.set(bundleHandle, harden(absolutePaths));
-        return bundleHandle;
-      };
-      /** @type {import('./externalTypes.js').PublishBundleRef} */
-      const publishRef = async handleP => {
-        const handle = await handleP;
-        bundleHandleToAbsolutePaths.has(handle) ||
-          Fail`${handle} not in installed bundles`;
-        return handle;
-      };
-      const proposal = await ns[entrypoint]({ publishRef, install }, ...args);
-
-      // Add the proposal bundle handles in sorted order.
-      const bundleSpecEntries = [...thisProposalBundleHandles.keys()]
-        .map(handle => [handle, bundleHandleToAbsolutePaths.get(handle)])
-        .sort(([_hnda, { source: a }], [_hndb, { source: b }]) => {
-          if (a < b) {
-            return -1;
+            ({
+              module,
+              entrypoint = 'defaultProposalBuilder',
+              args = [],
+            } = coreProposal);
           }
-          if (a > b) {
-            return 1;
-          }
-          return 0;
-        })
-        .map(([handle, absolutePaths], j) => {
-          // Transform the bundle handle identity into a bundleName reference.
-          handle.bundleName = `coreProposal${thisProposalSequence}_${j}`;
-          harden(handle);
-
-          /** @type {[string, { sourceSpec: string }]} */
-          const specEntry = [
-            handle.bundleName,
-            { sourceSpec: absolutePaths.source },
-          ];
-          return specEntry;
-        });
-
-      // Now that we've assigned all the bundleNames and hardened the
-      // handles, we can extract the behavior bundle.
-      const { sourceSpec, getManifestCall } = await deeplyFulfilledObject(
-        harden(proposal),
-      );
-
-      const behaviorSource = pathResolve(initDir, sourceSpec);
-      const behaviors = await import(behaviorSource);
-      const [exportedGetManifest, ...manifestArgs] = getManifestCall;
-      const { manifest: overrideManifest } = await behaviors[
-        exportedGetManifest
-      ](harden({ restoreRef: () => null }), ...manifestArgs);
-
-      const behaviorBundleHandle = harden({
-        bundleName: `coreProposal${thisProposalSequence}_behaviors`,
-      });
-      const behaviorAbsolutePaths = harden({
-        source: behaviorSource,
-      });
-      bundleHandleToAbsolutePaths.set(
-        behaviorBundleHandle,
-        behaviorAbsolutePaths,
-      );
-
-      bundleSpecEntries.unshift([
-        behaviorBundleHandle.bundleName,
-        { sourceSpec: behaviorAbsolutePaths.source },
-      ]);
-
-      return harden({
-        ref: behaviorBundleHandle,
-        call: getManifestCall,
-        overrideManifest,
-        bundleSpecs: bundleSpecEntries,
-      });
-    }),
+
+          typeof module === 'string' ||
+            Fail`coreProposal module ${module} must be string`;
+          typeof entrypoint === 'string' ||
+            Fail`coreProposal entrypoint ${entrypoint} must be string`;
+          Array.isArray(args) || Fail`coreProposal args ${args} must be array`;
+
+          const thisProposalBundleHandles = new Set();
+          assert(getSequenceForProposal);
+          const thisProposalSequence = getSequenceForProposal(key);
+          const initPath = findModule(dirname, module);
+          const initDir = path.dirname(initPath);
+          /** @type {Record<string, import('./externalTypes.js').CoreEvalBuilder>} */
+          const ns = await import(initPath);
+          const install = (srcSpec, bundlePath) => {
+            const absoluteSrc = findModule(initDir, srcSpec);
+            const bundleHandle = {};
+            const absolutePaths = { source: absoluteSrc };
+            if (bundlePath) {
+              const absoluteBundle = pathResolve(initDir, bundlePath);
+              absolutePaths.bundle = absoluteBundle;
+              const oldSource = bundleToSource.get(absoluteBundle);
+              if (oldSource) {
+                oldSource === absoluteSrc ||
+                  Fail`${bundlePath} already installed from ${oldSource}, now ${absoluteSrc}`;
+              } else {
+                bundleToSource.set(absoluteBundle, absoluteSrc);
+              }
+            }
+            // Don't harden the bundleHandle since we need to set the bundleName on
+            // its unique identity later.
+            thisProposalBundleHandles.add(bundleHandle);
+            bundleHandleToAbsolutePaths.set(
+              bundleHandle,
+              harden(absolutePaths),
+            );
+            return bundleHandle;
+          };
+          /** @type {import('./externalTypes.js').PublishBundleRef} */
+          const publishRef = async handleP => {
+            const handle = await handleP;
+            bundleHandleToAbsolutePaths.has(handle) ||
+              Fail`${handle} not in installed bundles`;
+            return handle;
+          };
+          const proposal = await ns[entrypoint](
+            {
+              publishRef,
+              // @ts-expect-error not statically verified to return a full obj
+              install,
+            },
+            ...args,
+          );
+
+          // Add the proposal bundle handles in sorted order.
+          const bundleSpecEntries = await Promise.all(
+            [...thisProposalBundleHandles.keys()]
+              .map(handle => [handle, bundleHandleToAbsolutePaths.get(handle)])
+              .sort(([_hnda, { source: a }], [_hndb, { source: b }]) => {
+                if (a < b) {
+                  return -1;
+                }
+                if (a > b) {
+                  return 1;
+                }
+                return 0;
+              })
+              .map(async ([handle, absolutePaths], k) => {
+                // Transform the bundle handle identity into a bundleName reference.
+                const specEntry = await handleToBundleSpec(
+                  handle,
+                  absolutePaths.source,
+                  thisProposalSequence,
+                  String(k),
+                );
+                harden(handle);
+                return specEntry;
+              }),
+          );
+
+          // Now that we've assigned all the bundleNames and hardened the
+          // handles, we can extract the behavior bundle.
+          const { sourceSpec, getManifestCall } = await deeplyFulfilledObject(
+            harden(proposal),
+          );
+
+          const proposalSource = pathResolve(initDir, sourceSpec);
+          const proposalNS = await import(proposalSource);
+          const [manifestGetterName, ...manifestGetterArgs] = getManifestCall;
+          manifestGetterName in proposalNS ||
+            Fail`proposal ${proposalSource} missing export ${manifestGetterName}`;
+          const { manifest: customManifest } = await proposalNS[
+            manifestGetterName
+          ](harden({ restoreRef: () => null }), ...manifestGetterArgs);
+
+          const behaviorBundleHandle = {};
+          const specEntry = await handleToBundleSpec(
+            behaviorBundleHandle,
+            proposalSource,
+            thisProposalSequence,
+            'proposalNS',
+          );
+          bundleSpecEntries.unshift(specEntry);
+
+          bundleHandleToAbsolutePaths.set(
+            behaviorBundleHandle,
+            harden({
+              source: proposalSource,
+            }),
+          );
+
+          return /** @type {const} */ ([
+            key,
+            {
+              ref: behaviorBundleHandle,
+              call: getManifestCall,
+              customManifest,
+              bundleSpecs: bundleSpecEntries,
+            },
+          ]);
+        }),
+      ),
+    ),
   );
 
   // Extract all the bundle specs in already-sorted order.
   const bundles = Object.fromEntries(
-    extracted.flatMap(({ bundleSpecs }) => bundleSpecs),
+    extractedSteps.flatMap(step =>
+      step.flatMap(([_key, { bundleSpecs }]) => bundleSpecs),
+    ),
   );
   harden(bundles);
 
-  // Extract the manifest references and calls.
-  const makeCPArgs = extracted.map(({ ref, call, overrideManifest }) => ({
-    ref,
-    call,
-    overrideManifest,
-  }));
-  harden(makeCPArgs);
+  const codeSteps = extractedSteps.map(extractedStep => {
+    // Extract the manifest references and calls.
+    const metadataRecords = extractedStep.map(([_key, extractedSpec]) => {
+      const { ref, call, customManifest } = extractedSpec;
+      return { ref, call, customManifest };
+    });
+    harden(metadataRecords);
 
-  const code = `\
-// This is generated by @agoric/cosmic-swingset/src/extract-proposal.js - DO NOT EDIT
+    const code = `\
+// This is generated by @agoric/deploy-script-support/src/extract-proposal.js - DO NOT EDIT
 /* eslint-disable */
 
-const makeCoreProposalArgs = harden(${stringify(makeCPArgs, true)});
-
-const makeCoreProposalBehavior = ${makeCoreProposalBehavior};
+const metadataRecords = harden(${stringify(metadataRecords, true)});
 
-(${makeEnactCoreProposals})({ makeCoreProposalArgs, E });
+// Make an enactCoreProposals function and "export" it by way of script completion value.
+// It is constructed by an IIFE to ensure the absence of global bindings for
+// makeCoreProposalBehavior and makeEnactCoreProposals (the latter referencing the former),
+// which may not be necessary but preserves behavior pre-dating
+// https://github.com/Agoric/agoric-sdk/pull/8712 .
+const enactCoreProposals = ((
+  makeCoreProposalBehavior = ${makeCoreProposalBehavior},
+  makeEnactCoreProposals = ${makeEnactCoreProposals},
+) => makeEnactCoreProposals({ metadataRecords, E }))();
+enactCoreProposals;
 `;
+    return defangAndTrim(code);
+  });
 
   // console.debug('created bundles from proposals:', coreProposals, bundles);
-  return {
+  return harden({
     bundles,
-    code: defangAndTrim(code),
+    codeSteps,
     bundleHandleToAbsolutePaths,
-  };
+  });
 };

package/src/getBundlerMaker.js

@@ -13,6 +13,9 @@
 import { E } from '@endo/far';
 import url from 'url';
 
+/** @typedef {ReturnType<import('./endo-pieces-contract.js')['start']>['publicFacet']} BundleMaker */
+/** @typedef {ReturnType<BundleMaker['makeBundler']>} Bundler */
+
 export const makeGetBundlerMaker =
   (homeP, { lookup, bundleSource }) =>
   async ({
@@ -20,6 +23,7 @@ export const makeGetBundlerMaker =
     log = console.log,
   } = {}) => {
     const { board: optionalBoard, zoe, scratch } = await homeP;
+    /** @type {() => Promise<BundleMaker>} */
     const lookupOrCreate = async () => {
       // Locate the bundler maker if any already exists at the given path.
       let bundlerMaker = await lookup(JSON.parse(BUNDLER_MAKER_LOOKUP));

package/src/helpers.js

@@ -1,5 +1,7 @@
 // @ts-check
-import '@agoric/zoe/exported.js';
+
+/// <reference path="../../zoe/exported.js" />
+
 import { E } from '@endo/far';
 import bundleSource from '@endo/bundle-source';
 
@@ -15,7 +17,7 @@ import { makeSaveIssuer } from './saveIssuer.js';
 import { makeGetBundlerMaker } from './getBundlerMaker.js';
 import { assertOfferResult } from './assertOfferResult.js';
 import { installInPieces } from './installInPieces.js';
-import { makeWriteCoreProposal } from './writeCoreProposal.js';
+import { makeWriteCoreEval } from './writeCoreEvalParts.js';
 
 export * from '@agoric/internal/src/node/createBundles.js';
 
@@ -135,8 +137,16 @@ export const makeHelpers = async (homePromise, endowments) => {
     get getBundlerMaker() {
       return makeGetBundlerMaker(homePromise, { bundleSource, lookup });
     },
+    /** @returns {import('./writeCoreEvalParts.js').WriteCoreEval} */
+    get writeCoreEval() {
+      return makeWriteCoreEval(homePromise, endowments, {
+        getBundleSpec: deps.cacheAndGetBundleSpec,
+        getBundlerMaker: helpers.getBundlerMaker,
+      });
+    },
+    /** @deprecated use writeCoreEval */
     get writeCoreProposal() {
-      return makeWriteCoreProposal(homePromise, endowments, {
+      return makeWriteCoreEval(homePromise, endowments, {
         getBundleSpec: deps.cacheAndGetBundleSpec,
         getBundlerMaker: helpers.getBundlerMaker,
       });

package/src/install.js

@@ -3,20 +3,11 @@ import './externalTypes.js';
 
 import { E } from '@endo/far';
 
-/** @typedef {import('@agoric/deploy-script-support/src/externalTypes').Petname} Petname */
-
-/**
- * @callback BundleSource
- * @param {string} startFilename - the filepath to start the bundling from
- * @param {ModuleFormat | BundleOptions} [moduleFormat]
- * @param {object} [powers]
- * @param {ReadFn} [powers.read]
- * @param {CanonicalFn} [powers.canonical]
- */
+/** @import {Petname} from '@agoric/deploy-script-support/src/externalTypes.js' */
 
 // XXX board is Board but specifying that leads to type errors with imports which aren't worth fixing right now
 /**
- * @param {BundleSource} bundleSource
+ * @param {typeof import('@endo/bundle-source')['default']} bundleSource
  * @param {ERef<ZoeService>} zoe
  * @param {ERef<import('./startInstance.js').InstallationManager>} installationManager
  * @param {ERef<any>} board

package/src/offer.js

@@ -4,7 +4,7 @@ import { assert } from '@agoric/assert';
 // Avoid pulling in too many dependencies like notifiers
 import { AmountMath } from '@agoric/ertp/src/amountMath.js';
 
-/** @typedef {import('@agoric/deploy-script-support/src/externalTypes').Petname} Petname */
+/** @import {Petname} from '@agoric/deploy-script-support/src/externalTypes.js' */
 
 /**
  * @typedef {object} OfferHelperConfig
@@ -19,7 +19,7 @@ import { AmountMath } from '@agoric/ertp/src/amountMath.js';
  * @param {ERef<any>} walletAdmin - an internal type of the
  * wallet, not defined here
  * @param {ERef<ZoeService>} zoe
- * @param {ERef<Purse>} zoeInvitationPurse
+ * @param {ERef<Purse<'set', InvitationDetails>>} zoeInvitationPurse
  */
 export const makeOfferAndFindInvitationAmount = (
   walletAdmin,
@@ -28,7 +28,7 @@ export const makeOfferAndFindInvitationAmount = (
 ) => {
   /**
    * @param {Record<string, any>} invitationDetailsCriteria
-   * @returns {Promise<Amount>} invitationAmount
+   * @returns {Promise<InvitationAmount>} invitationAmount
    */
   const findInvitationAmount = async invitationDetailsCriteria => {
     const invitationAmount = await E(zoeInvitationPurse).getCurrentAmount();
@@ -114,9 +114,8 @@ export const makeOfferAndFindInvitationAmount = (
     } = config;
 
     const invitationToUse = getInvitation(invitation, partialInvitationDetails);
-    const invitationDetails = await E(zoe).getInvitationDetails(
-      invitationToUse,
-    );
+    const invitationDetails =
+      await E(zoe).getInvitationDetails(invitationToUse);
     const payments = withdrawPayments(proposal, paymentsWithPursePetnames);
 
     const seat = E(zoe).offer(invitationToUse, proposal, payments);

package/src/saveIssuer.js

@@ -1,12 +1,12 @@
 // @ts-check
 import { E } from '@endo/far';
 
-/** @typedef {import('@agoric/deploy-script-support/src/externalTypes').Petname} Petname */
+/** @import {Petname} from '@agoric/deploy-script-support/src/externalTypes.js' */
 
 /**
  * @param {ERef<any>} walletAdmin - an internal type of the
  * wallet, not defined here
- * @param {ERef<import('./startInstance').IssuerManager>} issuerManager
+ * @param {ERef<import('./startInstance.js').IssuerManager>} issuerManager
  */
 export const makeSaveIssuer = (walletAdmin, issuerManager) => {
   /**

package/src/startInstance.js

@@ -2,7 +2,7 @@
 import { assert } from '@agoric/assert';
 import { E, passStyleOf } from '@endo/far';
 
-/** @typedef {import('@agoric/deploy-script-support/src/externalTypes').Petname} Petname */
+/** @import {Petname} from '@agoric/deploy-script-support/src/externalTypes.js' */
 
 /**
  * @template T
@@ -100,9 +100,8 @@ export const makeStartInstance = (
         `creatorInvitation must be defined to be deposited`,
       );
       console.log(`-- Adding Invitation for: ${instancePetname}`);
-      const invitationAmount = await E(zoeInvitationPurse).deposit(
-        creatorInvitation,
-      );
+      const invitationAmount =
+        await E(zoeInvitationPurse).deposit(creatorInvitation);
       console.log(`- Created Contract Instance: ${instancePetname}`);
 
       const creatorInvitationDetails = invitationAmount.value[0];