@agoric/deploy-script-support 0.10.4-dev-27cc9b8.0 → 0.10.4-dev-96c19f5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/deploy-script-support",
-  "version": "0.10.4-dev-27cc9b8.0+27cc9b8",
+  "version": "0.10.4-dev-96c19f5.0+96c19f5",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
@@ -34,14 +34,14 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-27cc9b8.0+27cc9b8",
-    "@agoric/ertp": "0.16.3-dev-27cc9b8.0+27cc9b8",
-    "@agoric/import-manager": "0.3.12-dev-27cc9b8.0+27cc9b8",
-    "@agoric/internal": "0.3.3-dev-27cc9b8.0+27cc9b8",
-    "@agoric/notifier": "0.6.3-dev-27cc9b8.0+27cc9b8",
-    "@agoric/store": "0.9.3-dev-27cc9b8.0+27cc9b8",
-    "@agoric/time": "0.3.3-dev-27cc9b8.0+27cc9b8",
-    "@agoric/zoe": "0.26.3-dev-27cc9b8.0+27cc9b8",
+    "@agoric/assert": "0.6.1-dev-96c19f5.0+96c19f5",
+    "@agoric/ertp": "0.16.3-dev-96c19f5.0+96c19f5",
+    "@agoric/import-manager": "0.3.12-dev-96c19f5.0+96c19f5",
+    "@agoric/internal": "0.3.3-dev-96c19f5.0+96c19f5",
+    "@agoric/notifier": "0.6.3-dev-96c19f5.0+96c19f5",
+    "@agoric/store": "0.9.3-dev-96c19f5.0+96c19f5",
+    "@agoric/time": "0.3.3-dev-96c19f5.0+96c19f5",
+    "@agoric/zoe": "0.26.3-dev-96c19f5.0+96c19f5",
     "@endo/base64": "^1.0.5",
     "@endo/bundle-source": "^3.2.3",
     "@endo/far": "^1.1.2",
@@ -51,7 +51,7 @@
     "@endo/zip": "^1.0.5"
   },
   "devDependencies": {
-    "@agoric/vats": "0.15.2-dev-27cc9b8.0+27cc9b8",
+    "@agoric/vats": "0.15.2-dev-96c19f5.0+96c19f5",
     "@endo/init": "^1.1.2",
     "ava": "^5.3.0",
     "import-meta-resolve": "^2.2.1"
@@ -74,5 +74,5 @@
   "typeCoverage": {
     "atLeast": 81.63
   },
-  "gitHead": "27cc9b8be59abb048f1ea226b96697c3dccc4d0f"
+  "gitHead": "96c19f54bd17fd616883713d372a9dc8ca0140f9"
 }

package/src/coreProposalBehavior.js

@@ -24,7 +24,7 @@ const t = 'makeCoreProposalBehavior';
  * They are merged with all of the manifest getter's permits to produce the
  * total permits needed by the resulting core proposal (such as might be---and
  * generally are---written into a *-permit.json file).
- * @see {@link ./writeCoreProposal.js}
+ * @see {@link ./writeCoreEvalParts.js}
  */
 export const permits = {
   consume: { agoricNamesAdmin: t, vatAdminSvc: t, zoe: t },
@@ -106,7 +106,7 @@ export const makeCoreProposalBehavior = ({
     // HOWEVER, do note that this function is invoked with at least the *union* of powers
     // required by individual moduleBehaviors declared by the manifest getter, which is
     // necessary so it can use `runModuleBehaviors` to provide the appropriate subset to
-    // each one (see ./writeCoreProposal.js).
+    // each one (see ./writeCoreEvalParts.js).
     // Handle `powers` with the requisite care.
     const {
       consume: { vatAdminSvc, zoe, agoricNamesAdmin },

package/src/externalTypes.js

@@ -9,12 +9,6 @@ export {};
  * origin.  We are migrating away from using plain strings, for consistency.
  */
 
-/**
- * @typedef ProposalResult
- * @property {string} sourceSpec
- * @property {[exportedGetManifest: string, ...manifestArgs: any[]]} getManifestCall
- */
-
 /**
  * @typedef {{fileName?: string} & ({ bundleName: string } | { bundleID: string}) } ManifestBundleRef
  */
@@ -34,12 +28,22 @@ export {};
  */
 
 /**
- * @callback ProposalBuilder
+ * @typedef CoreEvalDescriptor
+ * @property {string} sourceSpec import specifier for a module
+ * @property {[manifestGetterName: string, ...manifestGetterArgs: any[]]} getManifestCall
+ *   the name of a function exported by the module and arguments to invoke it
+ *   with in order to get a manifest (a Record that associates functions to be
+ *   invoked and permits defining bootstrap-space powers they will have access
+ *   to, see {@link ../README.md} and {@link runModuleBehaviors})
+ */
+
+/**
+ * @callback CoreEvalBuilder
  * @param {{
  *   publishRef: PublishBundleRef,
  *   install: InstallEntrypoint,
  *   wrapInstall?: <T extends InstallEntrypoint>(f: T) => T }
  * } powers
  * @param {...any} args
- * @returns {Promise<ProposalResult>}
+ * @returns {Promise<CoreEvalDescriptor>}
  */

package/src/extract-proposal.js

@@ -156,7 +156,7 @@ export const extractCoreProposalBundles = async (
           const thisProposalSequence = getSequenceForProposal(key);
           const initPath = findModule(dirname, module);
           const initDir = path.dirname(initPath);
-          /** @type {Record<string, import('./externalTypes.js').ProposalBuilder>} */
+          /** @type {Record<string, import('./externalTypes.js').CoreEvalBuilder>} */
           const ns = await import(initPath);
           const install = (srcSpec, bundlePath) => {
             const absoluteSrc = findModule(initDir, srcSpec);

package/src/helpers.js

@@ -17,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';
 
@@ -137,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/{writeCoreProposal.js → writeCoreEvalParts.js}

@@ -5,28 +5,40 @@ import { deeplyFulfilled } from '@endo/marshal';
 
 import { createBundles } from '@agoric/internal/src/node/createBundles.js';
 import { defangAndTrim, mergePermits, stringify } from './code-gen.js';
-import { makeCoreProposalBehavior, permits } from './coreProposalBehavior.js';
+import {
+  makeCoreProposalBehavior,
+  permits as defaultPermits,
+} from './coreProposalBehavior.js';
 
 /**
- * @callback WriteCoreProposal
- * @param {string} filePrefix
- * @param {import('./externalTypes.js').ProposalBuilder} proposalBuilder
+ * @import {CoreEvalDescriptor} from './externalTypes.js';
+ */
+
+/**
+ * @callback WriteCoreEval write to disk the files needed for a CoreEval (js code to`${filePrefix}.js`, permits to `${filePrefix}-permit.json`, an overall
+ *   summary to `${filePrefix}-plan.json), plus whatever bundles bundles the code loads)
+ * see CoreEval in {@link '/golang/cosmos/x/swingset/types/swingset.pb.go'}
+ * @param {string} filePrefix name on disk
+ * @param {import('./externalTypes.js').CoreEvalBuilder} builder
  * @returns {Promise<void>}
  */
 
 /**
  *
  * @param {*} homeP
- * @param {*} endowments
+ * @param {{
+ *   bundleSource: (path: string) => Promise<NodeModule>,
+ *   pathResolve: (path: string) => string,
+ * }} endowments
  * @param {{
  *   getBundlerMaker: () => Promise<import('./getBundlerMaker.js').BundleMaker>,
  *   getBundleSpec: (...args: *) => Promise<import('./externalTypes.js').ManifestBundleRef>,
  *   log?: typeof console.log,
  *   writeFile?: typeof fs.promises.writeFile
  * }} io
- * @returns {WriteCoreProposal}
+ * @returns {WriteCoreEval}
  */
-export const makeWriteCoreProposal = (
+export const makeWriteCoreEval = (
   homeP,
   endowments,
   {
@@ -49,16 +61,21 @@ export const makeWriteCoreProposal = (
     return bundlerCache;
   };
 
-  const mergeProposalPermit = async (proposal, additionalPermits) => {
+  /**
+   *
+   * @param {CoreEvalDescriptor} coreEval
+   * @param {*} additionalPermits
+   */
+  const mergeEvalPermit = async (coreEval, additionalPermits) => {
     const {
       sourceSpec,
       getManifestCall: [manifestGetterName, ...manifestGetterArgs],
-    } = proposal;
+    } = coreEval;
 
-    const proposalNS = await import(pathResolve(sourceSpec));
+    const moduleNamespace = await import(pathResolve(sourceSpec));
 
     // We only care about the manifest, not any restoreRef calls.
-    const { manifest } = await proposalNS[manifestGetterName](
+    const { manifest } = await moduleNamespace[manifestGetterName](
       harden({ restoreRef: x => `restoreRef:${x}` }),
       ...manifestGetterArgs,
     );
@@ -74,8 +91,8 @@ export const makeWriteCoreProposal = (
     /** @type {Promise<import('./externalTypes.js').ManifestBundleRef | undefined>} */ (
       Promise.resolve()
     );
-  /** @type {WriteCoreProposal} */
-  const writeCoreProposal = async (filePrefix, proposalBuilder) => {
+  /** @type {WriteCoreEval} */
+  const writeCoreEval = async (filePrefix, builder) => {
     /**
      *
      * @param {string} entrypoint
@@ -131,23 +148,23 @@ export const makeWriteCoreProposal = (
       return harden(ref);
     };
 
-    // Create the proposal structure.
-    const proposal = await deeplyFulfilled(
-      harden(proposalBuilder({ publishRef, install })),
+    // Create the eval structure.
+    const evalDescriptor = await deeplyFulfilled(
+      harden(builder({ publishRef, install })),
     );
-    const { sourceSpec, getManifestCall } = proposal;
+    const { sourceSpec, getManifestCall } = evalDescriptor;
     // console.log('created', { filePrefix, sourceSpec, getManifestCall });
 
     // Extract the top-level permit.
-    const { permits: proposalPermit, manifest: customManifest } =
-      await mergeProposalPermit(proposal, permits);
+    const { permits: evalPermits, manifest: customManifest } =
+      await mergeEvalPermit(evalDescriptor, defaultPermits);
 
     // Get an install
     const manifestBundleRef = await publishRef(install(sourceSpec));
 
     // console.log('writing', { filePrefix, manifestBundleRef, sourceSpec });
     const code = `\
-// This is generated by writeCoreProposal; please edit!
+// This is generated by writeCoreEval; please edit!
 /* eslint-disable */
 
 const manifestBundleRef = ${stringify(manifestBundleRef)};
@@ -164,21 +181,18 @@ behavior;
 
     const trimmed = defangAndTrim(code);
 
-    const proposalPermitJsonFile = `${filePrefix}-permit.json`;
-    log(`creating ${proposalPermitJsonFile}`);
-    await writeFile(
-      proposalPermitJsonFile,
-      JSON.stringify(proposalPermit, null, 2),
-    );
+    const permitFile = `${filePrefix}-permit.json`;
+    log(`creating ${permitFile}`);
+    await writeFile(permitFile, JSON.stringify(evalPermits, null, 2));
 
-    const proposalJsFile = `${filePrefix}.js`;
-    log(`creating ${proposalJsFile}`);
-    await writeFile(proposalJsFile, trimmed);
+    const codeFile = `${filePrefix}.js`;
+    log(`creating ${codeFile}`);
+    await writeFile(codeFile, trimmed);
 
     const plan = {
       name: filePrefix,
-      script: proposalJsFile,
-      permit: proposalPermitJsonFile,
+      script: codeFile,
+      permit: permitFile,
       bundles,
     };
 
@@ -189,13 +203,15 @@ behavior;
 
     log(`\
 You can now run a governance submission command like:
-  agd tx gov submit-proposal swingset-core-eval ${proposalPermitJsonFile} ${proposalJsFile} \\
-    --title="Enable <something>" --description="Evaluate ${proposalJsFile}" --deposit=1000000ubld \\
+  agd tx gov submit-proposal swingset-core-eval ${permitFile} ${codeFile} \\
+    --title="Enable <something>" --description="Evaluate ${codeFile}" --deposit=1000000ubld \\
     --gas=auto --gas-adjustment=1.2
 Remember to install bundles before submitting the proposal:
   ${cmds.join('\n  ')}
 `);
   };
 
-  return writeCoreProposal;
+  return writeCoreEval;
 };
+/** @deprecated use makeWriteCoreEval */
+export const makeWriteCoreProposal = makeWriteCoreEval;