chore(types): define DeployScriptFunction

Author: turadg

packages/builders/scripts/inter-protocol/add-collateral-core.js

@@ -112,7 +112,10 @@ export default async (homeP, endowments) => {
 
   await writeCoreEval('gov-add-collateral', defaultProposalBuilder);
   await writeCoreEval('gov-start-psm', opts =>
-    // @ts-expect-error XXX makeInstallCache types
-    psmProposalBuilder({ ...opts, wrapInstall: tool.wrapInstall }),
+    psmProposalBuilder({
+      ...opts,
+      // @ts-expect-error XXX makeInstallCache types
+      wrapInstall: tool.wrapInstall,
+    }),
   );
 };

packages/deploy-script-support/src/cachedBundleSpec.js

@@ -6,6 +6,9 @@ import { Fail } from '@endo/errors';
  */
 export const makeCacheAndGetBundleSpec =
   (cacheDir, { now, fs, pathResolve }) =>
+  /**
+   * @param {Promise<import('@endo/bundle-source').BundleSourceResult<'endoZipBase64'>>} bundleP
+   */
   async bundleP => {
     const bundle = await bundleP;
     const { endoZipBase64Sha512: hash } = bundle;

packages/deploy-script-support/src/externalTypes.js

@@ -1,6 +1,10 @@
 // @ts-check
 export {};
 
+/**
+ * @import {NameHub} from '@agoric/vats';
+ */
+
 // TODO move this type somewhere better
 /**
  * @typedef {string | string[]} Petname A petname can either be a plain string
@@ -47,3 +51,41 @@ export {};
  * @param {...any} args
  * @returns {Promise<CoreEvalDescriptor>}
  */
+
+/**
+ * @typedef {{
+ *  bundleSource: typeof import('@endo/bundle-source').default,
+ *  cacheDir: string,
+ *  lookup: (...path: string[]) => unknown,
+ *  now: () => number,
+ *  pathResolve: (...path: string[]) => string,
+ *  publishBundle: PublishBundleRef,
+ * }} DeployScriptEndownments
+ */
+
+/**
+ * @typedef {{
+ *   scratch: ERef<import('@agoric/internal/src/scratch.js').ScratchPad>,
+ * }} CommonHome
+ */
+
+// TODO wallet as import('@agoric/wallet-backend/src/types').WalletAdmin once it's a module
+/**
+ * @typedef {CommonHome & {
+ * agoricNames: ERef<NameHub>,
+ * bank: ERef<import("@agoric/vats/src/vat-bank.js").Bank>,
+ * board: ERef<import("@agoric/vats").Board>,
+ * faucet: unknown,
+ * myAddressNameAdmin: ERef<import("@agoric/vats").NameAdmin>,
+ * namesByAddress: ERef<NameHub>,
+ * wallet: any,
+ * zoe: ERef<ZoeService>,
+ * }} AgSoloHome
+ */
+
+/**
+ * @callback DeployScriptFunction
+ * @param {Promise<CommonHome>} homeP
+ * @param {DeployScriptEndownments} endowments
+ * @returns {Promise<void>}
+ */

packages/deploy-script-support/src/helpers.js

@@ -52,6 +52,10 @@ const makeLazyObject = sourceObject => {
   return /** @type {T} */ (lazyObject);
 };
 
+/**
+ * @param {Promise<import('./externalTypes.js').CommonHome | import('./externalTypes.js').AgSoloHome>} homePromise
+ * @param {import('./externalTypes.js').DeployScriptEndownments} endowments
+ */
 export const makeHelpers = async (homePromise, endowments) => {
   // Endowments provided via `agoric run` or `agoric deploy`.
   const {
@@ -84,13 +88,15 @@ export const makeHelpers = async (homePromise, endowments) => {
       return E(deps.walletAdmin).getIssuerManager();
     },
     get offerAndFind() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return makeOfferAndFindInvitationAmount(
         deps.walletAdmin,
         deps.home.zoe,
         deps.zoeInvitationPurse,
       );
     },
     get walletAdmin() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return E(deps.home.wallet).getAdminFacet();
     },
     get zoeInvitationPurse() {
@@ -110,6 +116,7 @@ export const makeHelpers = async (homePromise, endowments) => {
       return deps.offerAndFind.findInvitationAmount;
     },
     get install() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return makeInstall(
         bundleSource,
         deps.home.zoe,
@@ -127,6 +134,7 @@ export const makeHelpers = async (homePromise, endowments) => {
       return makeSaveIssuer(deps.walletAdmin, deps.issuerManager);
     },
     get startInstance() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return makeStartInstance(
         deps.issuerManager,
         deps.instanceManager,

packages/deploy-script-support/src/writeCoreEvalParts.js

@@ -11,7 +11,8 @@ import {
 } from './coreProposalBehavior.js';
 
 /**
- * @import {CoreEvalDescriptor} from './externalTypes.js';
+ * @import {BundleSource, BundleSourceResult} from '@endo/bundle-source';
+ * @import {AgSoloHome, CanonicalHome, CommonHome, CoreEvalBuilder, CoreEvalDescriptor, ManifestBundleRef} from './externalTypes.js';
  */
 
 /**
@@ -27,20 +28,20 @@ import {
  *   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
+ * @param {CoreEvalBuilder} builder
  * @returns {Promise<CoreEvalPlan>}
  */
 
 /**
  *
- * @param {*} homeP
+ * @param {Promise<CommonHome | AgSoloHome>} homeP
  * @param {{
- *   bundleSource: (path: string) => Promise<NodeModule>,
+ *   bundleSource: BundleSource,
  *   pathResolve: (path: string) => string,
  * }} endowments
  * @param {{
  *   getBundlerMaker: () => Promise<import('./getBundlerMaker.js').BundleMaker>,
- *   getBundleSpec: (...args: *) => Promise<import('./externalTypes.js').ManifestBundleRef>,
+ *   getBundleSpec: (bundle: Promise<BundleSourceResult<'endoZipBase64'>>, getBundle: () => import('./getBundlerMaker.js').Bundler, opts?: any) => Promise<ManifestBundleRef>,
  *   log?: typeof console.log,
  *   writeFile?: typeof fs.promises.writeFile
  * }} io
@@ -63,6 +64,7 @@ export const makeWriteCoreEval = (
   const getBundler = () => {
     if (!bundlerCache) {
       bundlerCache = E(getBundlerMaker()).makeBundler({
+        // @ts-expect-error lazily resolved for AgSoloHome
         zoe: E.get(homeP).zoe,
       });
     }
@@ -95,17 +97,16 @@ export const makeWriteCoreEval = (
     };
   };
 
-  let mutex =
-    /** @type {Promise<import('./externalTypes.js').ManifestBundleRef | undefined>} */ (
-      Promise.resolve()
-    );
+  let mutex = /** @type {Promise<ManifestBundleRef | undefined>} */ (
+    Promise.resolve()
+  );
   /** @type {WriteCoreEval} */
   const writeCoreEval = async (filePrefix, builder) => {
     /**
      *
      * @param {string} entrypoint
      * @param {string} [bundlePath]
-     * @returns {Promise<NodeModule>}
+     * @returns {Promise<BundleSourceResult<'endoZipBase64'>>}
      */
     const getBundle = async (entrypoint, bundlePath) => {
       if (!bundlePath) {
@@ -125,7 +126,7 @@ export const makeWriteCoreEval = (
      * @param {string} entrypoint
      * @param {string} [bundlePath]
      * @param {unknown} [opts]
-     * @returns {Promise<import('./externalTypes.js').ManifestBundleRef>}
+     * @returns {Promise<ManifestBundleRef>}
      */
     const install = async (entrypoint, bundlePath, opts) => {
       const bundle = getBundle(entrypoint, bundlePath);
@@ -146,7 +147,7 @@ export const makeWriteCoreEval = (
 
     // Await a reference then publish to the board.
     const cmds = [];
-    /** @param {Promise<import('./externalTypes.js').ManifestBundleRef>} refP */
+    /** @param {Promise<ManifestBundleRef>} refP */
     const publishRef = async refP => {
       const { fileName, ...ref } = await refP;
       if (fileName) {

packages/inter-protocol/src/proposals/utils.js

@@ -100,9 +100,9 @@ const provideWhen = async (store, key, make) => {
 };
 
 /**
- * @param {{
+ * @param {Promise<{
  *   scratch: ERef<import('@agoric/internal/src/scratch.js').ScratchPad>;
- * }} homeP
+ * }>} homeP
  * @param {object} opts
  * @param {(specifier: string) => Promise<{ default: Bundle }>} opts.loadBundle
  * @param {string} [opts.installCacheKey]

tsconfig.build.json

@@ -25,7 +25,6 @@
         "**/dist",
         "**/docs",
         "**/*.umd.js",
-        "**/proposals",
         "**/scripts",
         "**/test"
     ],