@latticexyz/cli 0.0.0-main-20230704121617

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@latticexyz/cli",
+  "version": "0.0.0-main-20230704121617",
+  "description": "Command line interface for mud",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latticexyz/mud.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "src/index.ts",
+  "bin": {
+    "mud": "./dist/mud.js"
+  },
+  "dependencies": {
+    "@ethersproject/abi": "^5.7.0",
+    "@ethersproject/providers": "^5.7.2",
+    "@improbable-eng/grpc-web": "^0.15.0",
+    "@improbable-eng/grpc-web-node-http-transport": "^0.15.0",
+    "@typechain/ethers-v5": "^10.2.0",
+    "chalk": "^5.0.1",
+    "chokidar": "^3.5.3",
+    "dotenv": "^16.0.3",
+    "ejs": "^3.1.8",
+    "ethers": "^5.7.2",
+    "execa": "^7.0.0",
+    "glob": "^8.0.3",
+    "nice-grpc-web": "^2.0.1",
+    "openurl": "^1.1.1",
+    "path": "^0.12.7",
+    "strip-ansi": "^7.1.0",
+    "table": "^6.8.1",
+    "throttle-debounce": "^5.0.0",
+    "typechain": "^8.1.1",
+    "typescript": "^4.9.5",
+    "yargs": "^17.7.1",
+    "zod": "^3.21.4",
+    "zod-validation-error": "^1.3.0",
+    "@latticexyz/common": "1.42.0",
+    "@latticexyz/config": "1.42.0",
+    "@latticexyz/schema-type": "1.42.0",
+    "@latticexyz/services": "0.0.0-main-20230704121617",
+    "@latticexyz/solecs": "1.42.0",
+    "@latticexyz/std-contracts": "1.42.0",
+    "@latticexyz/store": "1.42.0",
+    "@latticexyz/utils": "1.42.0",
+    "@latticexyz/world": "1.42.0"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.1",
+    "@types/glob": "^7.2.0",
+    "@types/node": "^18.15.11",
+    "@types/openurl": "^1.0.0",
+    "@types/throttle-debounce": "^5.0.0",
+    "@types/yargs": "^17.0.10",
+    "ds-test": "https://github.com/dapphub/ds-test.git#c9ce3f25bde29fc5eb9901842bf02850dfd2d084",
+    "forge-std": "https://github.com/foundry-rs/forge-std.git#b4f121555729b3afb3c5ffccb62ff4b6e2818fd3",
+    "tsup": "^6.7.0",
+    "tsx": "^3.12.6",
+    "vitest": "0.31.4"
+  },
+  "gitHead": "914a1e0ae4a573d685841ca2ea921435057deb8f",
+  "scripts": {
+    "build": "pnpm run build:js",
+    "build:js": "tsup && chmod +x ./dist/mud.js",
+    "clean": "pnpm run clean:js",
+    "clean:js": "rimraf dist",
+    "dev": "tsup --watch",
+    "generate-test-tables": "tsx ./scripts/generate-test-tables.ts",
+    "lint": "eslint . --ext .ts",
+    "test": "tsc --noEmit && pnpm run generate-test-tables && forge test"
+  }
+}

package/src/commands/deploy.ts

@@ -0,0 +1,49 @@
+import type { CommandModule, Options } from "yargs";
+import { logError } from "../utils/errors";
+import { deployHandler, DeployOptions } from "../utils";
+
+export const yDeployOptions = {
+  configPath: { type: "string", desc: "Path to the config file" },
+  clean: { type: "boolean", desc: "Remove the build forge artifacts and cache directories before building" },
+  printConfig: { type: "boolean", desc: "Print the resolved config" },
+  profile: { type: "string", desc: "The foundry profile to use" },
+  debug: { type: "boolean", desc: "Print debug logs, like full error messages" },
+  priorityFeeMultiplier: {
+    type: "number",
+    desc: "Multiply the estimated priority fee by the provided factor",
+    default: 1,
+  },
+  saveDeployment: { type: "boolean", desc: "Save the deployment info to a file", default: true },
+  rpc: { type: "string", desc: "The RPC URL to use. Defaults to the RPC url from the local foundry.toml" },
+  worldAddress: { type: "string", desc: "Deploy to an existing World at the given address" },
+  srcDir: { type: "string", desc: "Source directory. Defaults to foundry src directory." },
+  disableTxWait: { type: "boolean", desc: "Disable waiting for transactions to be confirmed.", default: false },
+  pollInterval: {
+    type: "number",
+    desc: "Interval in miliseconds to use to poll for transaction receipts / block inclusion",
+    default: 1000,
+  },
+  skipBuild: { type: "boolean", desc: "Skip rebuilding the contracts before deploying" },
+} satisfies Record<keyof DeployOptions, Options>;
+
+const commandModule: CommandModule<DeployOptions, DeployOptions> = {
+  command: "deploy",
+
+  describe: "Deploy MUD contracts",
+
+  builder(yargs) {
+    return yargs.options(yDeployOptions);
+  },
+
+  async handler(args) {
+    try {
+      await deployHandler(args);
+    } catch (error: any) {
+      logError(error);
+      process.exit(1);
+    }
+    process.exit(0);
+  },
+};
+
+export default commandModule;

package/src/commands/dev-contracts.ts

@@ -0,0 +1,176 @@
+import type { CommandModule } from "yargs";
+import { anvil, forge, getRpcUrl, getScriptDirectory, getSrcDirectory } from "@latticexyz/common/foundry";
+import chalk from "chalk";
+import chokidar from "chokidar";
+import { loadConfig, resolveConfigPath } from "@latticexyz/config/node";
+import { StoreConfig } from "@latticexyz/store";
+import { tablegen } from "@latticexyz/store/codegen";
+import path from "path";
+import { tsgen } from "../render-ts";
+import { debounce } from "throttle-debounce";
+import { worldgenHandler } from "./worldgen";
+import { WorldConfig } from "@latticexyz/world";
+import { deployHandler, logError, printMUD, worldtypes } from "../utils";
+import { homedir } from "os";
+import { rmSync } from "fs";
+
+type Options = {
+  rpc?: string;
+  configPath?: string;
+  tsgenOutput: string;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "dev-contracts",
+
+  describe: "Start a development server for MUD contracts",
+
+  builder(yargs) {
+    return yargs.options({
+      rpc: {
+        type: "string",
+        decs: "RPC endpoint of the development node. If none is provided, an anvil instance is spawned in the background on port 8545.",
+      },
+      configPath: {
+        type: "string",
+        decs: "Path to MUD config",
+      },
+      tsgenOutput: { type: "string", demandOption: true, desc: "Directory to output MUD typescript definition files" },
+    });
+  },
+
+  async handler(args) {
+    if (!args.tsgenOutputDir) {
+      console.error("No output provided");
+    }
+
+    // Initial cleanup
+    await forge(["clean"]);
+
+    const rpc = args.rpc ?? (await getRpcUrl());
+    const configPath = args.configPath ?? (await resolveConfigPath(args.configPath));
+    const srcDirectory = await getSrcDirectory();
+    const scriptDirectory = await getScriptDirectory();
+    const initialConfig = (await loadConfig(configPath)) as StoreConfig & WorldConfig;
+
+    // Initial run of all codegen steps before starting anvil
+    // (so clients can wait for everything to be ready before starting)
+    await handleConfigChange(initialConfig);
+    await handleContractsChange(initialConfig);
+
+    // Start an anvil instance in the background if no RPC url is provided
+    if (!args.rpc) {
+      console.log(chalk.gray("Cleaning devnode cache"));
+      const userHomeDir = homedir();
+      rmSync(path.join(userHomeDir, ".foundry", "anvil", "tmp"), { recursive: true, force: true });
+
+      const anvilArgs = ["--block-time", "1", "--block-base-fee-per-gas", "0"];
+      anvil(anvilArgs);
+    }
+
+    const changedSinceLastHandled = {
+      config: false,
+      contracts: false,
+    };
+
+    const changeInProgress = {
+      current: false,
+    };
+
+    // Watch for changes
+    const configWatcher = chokidar.watch([configPath, srcDirectory]);
+    configWatcher.on("all", async (_, updatePath) => {
+      if (updatePath.includes(configPath)) {
+        changedSinceLastHandled.config = true;
+        // We trigger contract changes if the config changed here instead of
+        // listening to changes in the codegen directory to avoid an infinite loop
+        changedSinceLastHandled.contracts = true;
+      }
+
+      if (updatePath.includes(srcDirectory) || updatePath.includes(scriptDirectory)) {
+        // Ignore changes to codegen files to avoid an infinite loop
+        if (updatePath.includes(initialConfig.codegenDirectory)) return;
+        changedSinceLastHandled.contracts = true;
+      }
+
+      // Trigger debounced onChange
+      handleChange();
+    });
+
+    const handleChange = debounce(100, async () => {
+      // Avoid handling changes multiple times in parallel
+      if (changeInProgress.current) return;
+      changeInProgress.current = true;
+
+      // Reset dirty flags
+      const { config, contracts } = changedSinceLastHandled;
+      changedSinceLastHandled.config = false;
+      changedSinceLastHandled.contracts = false;
+
+      try {
+        // Load latest config
+        const mudConfig = (await loadConfig(configPath)) as StoreConfig & WorldConfig;
+
+        // Handle changes
+        if (config) await handleConfigChange(mudConfig);
+        if (contracts) await handleContractsChange(mudConfig);
+
+        await deploy();
+      } catch (error) {
+        console.error(chalk.red("MUD dev-contracts watcher failed to deploy config or contracts changes\n"));
+        logError(error);
+      }
+
+      changeInProgress.current = false;
+      if (changedSinceLastHandled.config || changedSinceLastHandled.contracts) {
+        console.log("Detected change while handling the previous change");
+        handleChange();
+      }
+
+      printMUD();
+      console.log("MUD watching for changes...");
+    });
+
+    /** Codegen to run if config changes */
+    async function handleConfigChange(config: StoreConfig & WorldConfig) {
+      console.log(chalk.blue("mud.config.ts changed - regenerating tables and recs types"));
+      // Run tablegen to generate tables based on the config
+      const outPath = path.join(srcDirectory, config.codegenDirectory);
+      await tablegen(config, outPath);
+
+      // Run tsgen to regenerate recs types based on the mud config
+      await tsgen(config, args.tsgenOutput);
+    }
+
+    /** Codegen to run if contracts changed */
+    async function handleContractsChange(config: StoreConfig & WorldConfig) {
+      console.log(chalk.blue("contracts changed - regenerating interfaces and contract types"));
+
+      // Run worldgen to generate interfaces based on the systems
+      await worldgenHandler({ config, clean: true, srcDir: srcDirectory });
+
+      // Build the contracts
+      await forge(["build"]);
+
+      // Run typechain to rebuild typescript types for the contracts
+      await worldtypes();
+    }
+
+    /** Run after codegen if either mud config or contracts changed */
+    async function deploy() {
+      console.log(chalk.blue("redeploying World"));
+      await deployHandler({
+        configPath,
+        skipBuild: true,
+        priorityFeeMultiplier: 1,
+        disableTxWait: true,
+        pollInterval: 1000,
+        saveDeployment: true,
+        srcDir: srcDirectory,
+        rpc,
+      });
+    }
+  },
+};
+
+export default commandModule;

package/src/commands/devnode.ts

@@ -0,0 +1,42 @@
+import { rmSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+import type { CommandModule } from "yargs";
+import { execa } from "execa";
+
+type Options = {
+  blocktime: number;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "devnode",
+
+  describe: "Start a local Ethereum node for development",
+
+  builder(yargs) {
+    return yargs.options({
+      blocktime: { type: "number", default: 1, decs: "Interval in which new blocks are produced" },
+    });
+  },
+
+  async handler({ blocktime }) {
+    console.log("Clearing devnode history");
+    const userHomeDir = homedir();
+    rmSync(path.join(userHomeDir, ".foundry", "anvil", "tmp"), { recursive: true, force: true });
+
+    const anvilArgs = ["-b", String(blocktime), "--block-base-fee-per-gas", "0"];
+    console.log(`Running: anvil ${anvilArgs.join(" ")}`);
+    const child = execa("anvil", anvilArgs, {
+      stdio: ["inherit", "inherit", "inherit"],
+    });
+
+    process.on("SIGINT", () => {
+      console.log("\ngracefully shutting down from SIGINT (Crtl-C)");
+      child.kill();
+      process.exit();
+    });
+    await child;
+  },
+};
+
+export default commandModule;

package/src/commands/faucet.ts

@@ -0,0 +1,60 @@
+import type { CommandModule } from "yargs";
+import { FaucetServiceDefinition } from "@latticexyz/services/faucet";
+import { createChannel, createClient } from "nice-grpc-web";
+import chalk from "chalk";
+import { NodeHttpTransport } from "@improbable-eng/grpc-web-node-http-transport";
+
+type Options = {
+  dripDev?: boolean;
+  faucetUrl: string;
+  address: string;
+};
+
+/**
+ * Create a FaucetServiceClient
+ * @param url FaucetService URL
+ * @returns FaucetServiceClient
+ */
+function createFaucetService(url: string) {
+  return createClient(FaucetServiceDefinition, createChannel(url, NodeHttpTransport()));
+}
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "faucet",
+
+  describe: "Interact with a MUD faucet",
+
+  builder(yargs) {
+    return yargs.options({
+      dripDev: {
+        type: "boolean",
+        desc: "Request a drip from the dev endpoint (requires faucet to have dev mode enabled)",
+        default: true,
+      },
+      faucetUrl: {
+        type: "string",
+        desc: "URL of the MUD faucet",
+        default: "https://faucet.testnet-mud-services.linfra.xyz",
+      },
+      address: {
+        type: "string",
+        desc: "Ethereum address to fund",
+        required: true,
+      },
+    });
+  },
+
+  async handler({ dripDev, faucetUrl, address }) {
+    const faucet = createFaucetService(faucetUrl);
+
+    if (dripDev) {
+      console.log(chalk.yellow("Dripping to", address));
+      await faucet.dripDev({ address });
+      console.log(chalk.yellow("Success"));
+    }
+
+    process.exit(0);
+  },
+};
+
+export default commandModule;

package/src/commands/gas-report.ts

@@ -0,0 +1,193 @@
+import type { CommandModule } from "yargs";
+import { readFileSync, writeFileSync } from "fs";
+import { execa } from "execa";
+import chalk from "chalk";
+import { table, getBorderCharacters } from "table";
+import stripAnsi from "strip-ansi";
+
+/**
+ * Print the gas report to the console, save it to a file and compare it to a previous gas report if provided.
+ *
+ * Requires foundry to be installed. Inherit from GasReporter and use startGasReport/endGasReport to measure gas used.
+ *
+ * ```solidity
+ * contract MyContractTest is Test, GasReporter {
+ *   function testBuffer() public pure {
+ *     startGasReport("allocate a buffer");
+ *     Buffer buffer = Buffer_.allocate(32);
+ *     endGasReport();
+ *
+ *     bytes32 value = keccak256("some data");
+ *
+ *     startGasReport("append 32 bytes to a buffer");
+ *     buffer.append(value);
+ *     endGasReport();
+ *  }
+ * }
+ * ```
+ */
+
+type Options = {
+  path: string[];
+  save?: string;
+  compare?: string;
+};
+
+type GasReportEntry = {
+  file: string;
+  test: string;
+  name: string;
+  gasUsed: number;
+  prevGasUsed?: number;
+};
+
+type GasReport = GasReportEntry[];
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "gas-report",
+
+  describe: "Create a gas report",
+
+  builder(yargs) {
+    return yargs.options({
+      save: { type: "string", desc: "Save the gas report to a file" },
+      compare: { type: "string", desc: "Compare to an existing gas report" },
+    });
+  },
+
+  async handler({ save, compare }) {
+    let gasReport: GasReport;
+    try {
+      gasReport = await runGasReport();
+    } catch (error) {
+      console.error(error);
+      setTimeout(() => process.exit());
+      return;
+    }
+
+    // If this gas report should be compared to an existing one, load the existing one
+    if (compare) {
+      try {
+        const compareGasReport: GasReport = JSON.parse(readFileSync(compare, "utf8"));
+        // Merge the previous gas report with the new one
+        gasReport = gasReport.map((entry) => {
+          const prevEntry = compareGasReport.find((e) => e.file === entry.file && e.name === entry.name);
+          return { ...entry, prevGasUsed: prevEntry?.gasUsed };
+        });
+      } catch {
+        console.log(chalk.red(`Gas report to compare not found: ${compare}`));
+        compare = undefined;
+      }
+    }
+
+    // Print gas report
+    printGasReport(gasReport, compare);
+
+    // Save gas report to file if requested
+    if (save) saveGasReport(gasReport, save);
+
+    process.exit(0);
+  },
+};
+
+export default commandModule;
+
+async function runGasReport(): Promise<GasReport> {
+  console.log("Running gas report");
+  const gasReport: GasReport = [];
+
+  // Extract the logs from the child process
+  let stdout: string;
+  try {
+    // Run the generated file using forge
+    const child = execa("forge", ["test", "-vvv"], {
+      stdio: ["inherit", "pipe", "inherit"],
+      env: { GAS_REPORTER_ENABLED: "true" },
+    });
+    stdout = (await child).stdout;
+  } catch (error: any) {
+    console.log(error.stdout ?? error);
+    console.log(chalk.red("\n-----------\nError while running the gas report (see above)"));
+    throw error;
+  }
+
+  // Extract the gas reports from the logs
+  const lines = stdout.split("\n").map(stripAnsi);
+  const gasReportPattern = /^\s*GAS REPORT: (\d+) (.*)$/;
+  const testFunctionPattern = /^\[(?:PASS|FAIL).*\] (\w+)\(\)/;
+  const testFilePattern = /^Running \d+ tests? for (.*):(.*)$/;
+
+  function nearestLine(pattern: RegExp, startIndex: number = lines.length - 1): number {
+    for (let i = startIndex; i >= 0; i--) {
+      const line = lines[i];
+      if (pattern.test(line)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const matches = lines[i].match(gasReportPattern);
+    if (!matches) continue;
+
+    const gasUsed = parseInt(matches[1]);
+    const name = matches[2];
+
+    const testFunctionLineIndex = nearestLine(testFunctionPattern, i);
+    if (testFunctionLineIndex === -1) {
+      throw new Error("Could not find nearest test function, did `forge test` output change?");
+    }
+    const testFileLineIndex = nearestLine(testFilePattern, testFunctionLineIndex);
+    if (testFileLineIndex === -1) {
+      throw new Error("Could not find nearest test filename, did `forge test` output change?");
+    }
+
+    const functionMatches = lines[testFunctionLineIndex].match(testFunctionPattern);
+    if (!functionMatches) {
+      throw new Error("Could not parse test function name, did `forge test` output change?");
+    }
+    const fileMatches = lines[testFileLineIndex].match(testFilePattern);
+    if (!fileMatches) {
+      throw new Error("Could not parse test filename, did `forge test` output change?");
+    }
+
+    const test = functionMatches[1];
+    const file = fileMatches[1];
+
+    gasReport.push({ file, test, name, gasUsed });
+  }
+
+  gasReport.sort((a, b) => a.file.localeCompare(b.file));
+
+  return gasReport;
+}
+
+function printGasReport(gasReport: GasReport, compare?: string) {
+  if (compare) console.log(chalk.bold(`Gas report compared to ${compare}`));
+
+  const headers = [
+    chalk.bold("File"),
+    chalk.bold("Test"),
+    chalk.bold("Name"),
+    chalk.bold("Gas used"),
+    ...(compare ? [chalk.bold("Prev gas used"), chalk.bold("Difference")] : []),
+  ];
+
+  const values = gasReport.map((entry) => {
+    const diff = entry.prevGasUsed ? entry.gasUsed - entry.prevGasUsed : 0;
+    const diffEntry = diff > 0 ? chalk.red(`+${diff}`) : diff < 0 ? chalk.green(`${diff}`) : diff;
+    const compareColumns = compare ? [entry.prevGasUsed ?? "n/a", diffEntry] : [];
+    const gasUsedEntry = diff > 0 ? chalk.red(entry.gasUsed) : diff < 0 ? chalk.green(entry.gasUsed) : entry.gasUsed;
+    return [entry.file, entry.test, entry.name, gasUsedEntry, ...compareColumns];
+  });
+
+  const rows = [headers, ...values];
+
+  console.log(table(rows, { border: getBorderCharacters("norc") }));
+}
+
+function saveGasReport(gasReport: GasReport, path: string) {
+  console.log(chalk.bold(`Saving gas report to ${path}`));
+  writeFileSync(path, `${JSON.stringify(gasReport, null, 2)}\n`);
+}

package/src/commands/hello.ts

@@ -0,0 +1,28 @@
+import type { CommandModule } from "yargs";
+
+type Options = {
+  name: string;
+  upper: boolean | undefined;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "hello <name>",
+
+  describe: "Greet <name> with Hello",
+
+  builder(yargs) {
+    return yargs
+      .options({
+        upper: { type: "boolean" },
+      })
+      .positional("name", { type: "string", demandOption: true });
+  },
+
+  handler({ name }) {
+    const greeting = `Gm, ${name}!`;
+    console.log(greeting);
+    process.exit(0);
+  },
+};
+
+export default commandModule;

package/src/commands/index.ts

@@ -0,0 +1,30 @@
+import { CommandModule } from "yargs";
+
+import devnode from "./devnode";
+import faucet from "./faucet";
+import gasReport from "./gas-report";
+import hello from "./hello";
+import tablegen from "./tablegen";
+import tsgen from "./tsgen";
+import deploy from "./deploy";
+import worldgen from "./worldgen";
+import setVersion from "./set-version";
+import test from "./test";
+import trace from "./trace";
+import devContracts from "./dev-contracts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Each command has different options
+export const commands: CommandModule<any, any>[] = [
+  deploy,
+  devnode,
+  faucet,
+  gasReport,
+  hello,
+  tablegen,
+  tsgen,
+  worldgen,
+  setVersion,
+  test,
+  trace,
+  devContracts,
+];