@latticexyz/cli 0.0.0-main-20230704121617

package/src/commands/set-version.ts

@@ -0,0 +1,200 @@
+import chalk from "chalk";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "fs";
+import path from "path";
+import type { CommandModule } from "yargs";
+import { MUDError } from "@latticexyz/common/errors";
+import { logError } from "../utils/errors";
+import localPackageJson from "../../package.json" assert { type: "json" };
+
+type Options = {
+  backup?: boolean;
+  force?: boolean;
+  restore?: boolean;
+  mudVersion?: string;
+  link?: string;
+};
+
+const BACKUP_FILE = ".mudbackup";
+const MUD_PREFIX = "@latticexyz";
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "set-version",
+
+  describe: "Install a custom MUD version and optionally backup the previously installed version",
+
+  builder(yargs) {
+    return yargs.options({
+      backup: { type: "boolean", description: `Back up the current MUD versions to "${BACKUP_FILE}"` },
+      force: {
+        type: "boolean",
+        description: `Backup fails if a "${BACKUP_FILE}" file is found, unless --force is provided`,
+      },
+      restore: { type: "boolean", description: `Restore the previous MUD versions from "${BACKUP_FILE}"` },
+      mudVersion: { alias: "v", type: "string", description: "The MUD version to install" },
+      link: { alias: "l", type: "string", description: "Relative path to the local MUD root directory to link" },
+    });
+  },
+
+  async handler(options) {
+    try {
+      if (!options.mudVersion && !options.link && !options.restore) {
+        throw new MUDError("`--mudVersion` or `--link` is required unless --restore is provided.");
+      }
+
+      // `link` and `mudVersion` are mutually exclusive
+      if (options.link && options.mudVersion) {
+        throw new MUDError("Options `--link` and `--mudVersion` are mutually exclusive");
+      }
+
+      // Resolve the `canary` version number if needed
+      options.mudVersion =
+        options.mudVersion === "canary" ? await getCanaryVersion(localPackageJson.name) : options.mudVersion;
+
+      // Read the current package.json
+      const rootPath = "./package.json";
+      const { workspaces } = updatePackageJson(rootPath, options);
+
+      // Load the package.json of each workspace
+      if (workspaces) {
+        for (const workspace of workspaces) {
+          const filePath = path.join(workspace, "/package.json");
+          updatePackageJson(filePath, options);
+        }
+      }
+    } catch (e) {
+      logError(e);
+    } finally {
+      process.exit(0);
+    }
+  },
+};
+
+function updatePackageJson(filePath: string, options: Options): { workspaces?: string[] } {
+  const { restore, force, link } = options;
+  let { backup, mudVersion } = options;
+
+  const backupFilePath = path.join(path.dirname(filePath), BACKUP_FILE);
+  const backupFileExists = existsSync(backupFilePath);
+
+  // Create a backup file for previous MUD versions by default if linking to local MUD
+  if (link && !backupFileExists) backup = true;
+
+  // If `backup` is true and force not set, check if a backup file already exists and throw an error if it does
+  if (backup && !force && backupFileExists) {
+    throw new MUDError(
+      `A backup file already exists at ${backupFilePath}.\nUse --force to overwrite it or --restore to restore it.`
+    );
+  }
+
+  const packageJson = readPackageJson(filePath);
+
+  // Load .mudbackup if `restore` is true
+  const backupJson = restore ? readPackageJson(backupFilePath) : undefined;
+
+  // Find all MUD dependencies
+  const mudDependencies: Record<string, string> = {};
+  for (const key in packageJson.dependencies) {
+    if (key.startsWith(MUD_PREFIX)) {
+      mudDependencies[key] = packageJson.dependencies[key];
+    }
+  }
+
+  // Find all MUD devDependencies
+  const mudDevDependencies: Record<string, string> = {};
+  for (const key in packageJson.devDependencies) {
+    if (key.startsWith(MUD_PREFIX)) {
+      mudDevDependencies[key] = packageJson.devDependencies[key];
+    }
+  }
+
+  // Back up the current dependencies if `backup` is true
+  if (backup) {
+    writeFileSync(
+      backupFilePath,
+      JSON.stringify({ dependencies: mudDependencies, devDependencies: mudDevDependencies }, null, 2)
+    );
+    console.log(chalk.green(`Backed up MUD dependencies from ${filePath} to ${backupFilePath}`));
+  }
+
+  // Update the dependencies
+  for (const key in packageJson.dependencies) {
+    if (key.startsWith(MUD_PREFIX)) {
+      packageJson.dependencies[key] = resolveMudVersion(key, "dependencies");
+    }
+  }
+
+  // Update the devDependencies
+  for (const key in packageJson.devDependencies) {
+    if (key.startsWith(MUD_PREFIX)) {
+      packageJson.devDependencies[key] = resolveMudVersion(key, "devDependencies");
+    }
+  }
+
+  // Write the updated package.json
+  writeFileSync(filePath, JSON.stringify(packageJson, null, 2) + "\n");
+
+  console.log(`Updating ${filePath}`);
+  logComparison(mudDependencies, packageJson.dependencies);
+  logComparison(mudDevDependencies, packageJson.devDependencies);
+
+  // Remove the backup file if `restore` is true and `backup` is false
+  // because the old backup file is no longer needed
+  if (restore && !backup) {
+    rmSync(backupFilePath);
+    console.log(chalk.green(`Cleaned up ${backupFilePath}`));
+  }
+
+  return packageJson;
+
+  function resolveMudVersion(key: string, type: "dependencies" | "devDependencies") {
+    if (restore && backupJson) return backupJson[type][key];
+    if (link) mudVersion = resolveLinkPath(filePath, link, key);
+    if (!mudVersion) return packageJson[type][key];
+    return mudVersion;
+  }
+}
+
+function readPackageJson(path: string): {
+  workspaces?: string[];
+  dependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+} {
+  try {
+    const jsonString = readFileSync(path, "utf8");
+    return JSON.parse(jsonString);
+  } catch {
+    throw new MUDError("Could not read JSON at " + path);
+  }
+}
+
+async function getCanaryVersion(pkg: string) {
+  try {
+    console.log(chalk.blue("fetching MUD canary version..."));
+    const result = await (await fetch(`https://registry.npmjs.org/${pkg}`)).json();
+    const canary = result["dist-tags"].canary;
+    console.log(chalk.green("MUD canary version:", canary));
+    return canary;
+  } catch (e) {
+    throw new MUDError(`Could not fetch canary version of ${pkg}`);
+  }
+}
+
+function logComparison(prev: Record<string, string>, curr: Record<string, string>) {
+  for (const key in prev) {
+    if (prev[key] !== curr[key]) {
+      console.log(`${key}: ${chalk.red(prev[key])} -> ${chalk.green(curr[key])}`);
+    }
+  }
+}
+
+/**
+ * Returns path of the package to link, given a path to a local MUD clone and a package
+ */
+function resolveLinkPath(packageJsonPath: string, mudLinkPath: string, pkg: string) {
+  const pkgName = pkg.replace(MUD_PREFIX, "");
+  const packageJsonToRootPath = path.relative(path.dirname(packageJsonPath), process.cwd());
+  const linkPath = path.join(packageJsonToRootPath, mudLinkPath, "packages", pkgName);
+  return "link:" + linkPath;
+}
+
+export default commandModule;

package/src/commands/tablegen.ts

@@ -0,0 +1,33 @@
+import path from "path";
+import type { CommandModule } from "yargs";
+import { loadConfig } from "@latticexyz/config/node";
+import { StoreConfig } from "@latticexyz/store";
+import { tablegen } from "@latticexyz/store/codegen";
+import { getSrcDirectory } from "@latticexyz/common/foundry";
+
+type Options = {
+  configPath?: string;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "tablegen",
+
+  describe: "Autogenerate MUD Store table libraries based on the config file",
+
+  builder(yargs) {
+    return yargs.options({
+      configPath: { type: "string", desc: "Path to the config file" },
+    });
+  },
+
+  async handler({ configPath }) {
+    const config = (await loadConfig(configPath)) as StoreConfig;
+    const srcDir = await getSrcDirectory();
+
+    await tablegen(config, path.join(srcDir, config.codegenDirectory));
+
+    process.exit(0);
+  },
+};
+
+export default commandModule;

package/src/commands/test.ts

@@ -0,0 +1,70 @@
+import type { CommandModule } from "yargs";
+import { anvil, forge, getRpcUrl } from "@latticexyz/common/foundry";
+import chalk from "chalk";
+import { rmSync, writeFileSync } from "fs";
+import { yDeployOptions } from "./deploy";
+import { deployHandler, DeployOptions } from "../utils";
+
+type Options = DeployOptions & { port?: number; worldAddress?: string; forgeOptions?: string };
+
+const WORLD_ADDRESS_FILE = ".mudtest";
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "test",
+
+  describe: "Run tests in MUD contracts",
+
+  builder(yargs) {
+    return yargs.options({
+      ...yDeployOptions,
+      port: { type: "number", description: "Port to run internal node for fork testing on", default: 4242 },
+      worldAddress: {
+        type: "string",
+        description:
+          "Address of an existing world contract. If provided, deployment is skipped and the RPC provided in the foundry.toml is used for fork testing.",
+      },
+      forgeOptions: { type: "string", description: "Options to pass to forge test" },
+    });
+  },
+
+  async handler(args) {
+    // Start an internal anvil process if no world address is provided
+    if (!args.worldAddress) {
+      const anvilArgs = ["--block-base-fee-per-gas", "0", "--port", String(args.port)];
+      anvil(anvilArgs);
+    }
+
+    const forkRpc = args.worldAddress ? await getRpcUrl(args.profile) : `http://127.0.0.1:${args.port}`;
+
+    const worldAddress =
+      args.worldAddress ??
+      (
+        await deployHandler({
+          ...args,
+          saveDeployment: false,
+          rpc: forkRpc,
+        })
+      ).worldAddress;
+
+    console.log(chalk.blue("World address", worldAddress));
+
+    // Create a temporary file to pass the world address to the tests
+    writeFileSync(WORLD_ADDRESS_FILE, worldAddress);
+
+    const userOptions = args.forgeOptions?.replaceAll("\\", "").split(" ") ?? [];
+    try {
+      const testResult = await forge(["test", "--fork-url", forkRpc, ...userOptions], {
+        profile: args.profile,
+      });
+      console.log(testResult);
+    } catch (e) {
+      console.error(e);
+    }
+
+    rmSync(WORLD_ADDRESS_FILE);
+
+    process.exit(0);
+  },
+};
+
+export default commandModule;

package/src/commands/trace.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from "fs";
+import type { CommandModule } from "yargs";
+import { ethers } from "ethers";
+
+import { loadConfig } from "@latticexyz/config/node";
+import { MUDError } from "@latticexyz/common/errors";
+import { cast, getRpcUrl, getSrcDirectory } from "@latticexyz/common/foundry";
+import { TableId } from "@latticexyz/common";
+import { StoreConfig } from "@latticexyz/store";
+import { resolveWorldConfig, WorldConfig } from "@latticexyz/world";
+import { IBaseWorld } from "@latticexyz/world/types/ethers-contracts/IBaseWorld";
+import IBaseWorldData from "@latticexyz/world/abi/IBaseWorld.sol/IBaseWorld.json" assert { type: "json" };
+import { getChainId, getExistingContracts } from "../utils";
+
+const systemsTableId = new TableId("", "Systems");
+
+type Options = {
+  tx: string;
+  worldAddress?: string;
+  configPath?: string;
+  profile?: string;
+  srcDir?: string;
+  rpc?: string;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "trace",
+
+  describe: "Display the trace of a transaction",
+
+  builder(yargs) {
+    return yargs.options({
+      tx: { type: "string", required: true, description: "Transaction hash to replay" },
+      worldAddress: {
+        type: "string",
+        description: "World contract address. Defaults to the value from worlds.json, based on rpc's chainId",
+      },
+      configPath: { type: "string", description: "Path to the config file" },
+      profile: { type: "string", description: "The foundry profile to use" },
+      srcDir: { type: "string", description: "Source directory. Defaults to foundry src directory." },
+      rpc: { type: "string", description: "json rpc endpoint. Defaults to foundry's configured eth_rpc_url" },
+    });
+  },
+
+  async handler(args) {
+    args.profile ??= process.env.FOUNDRY_PROFILE;
+    const { profile } = args;
+    args.srcDir ??= await getSrcDirectory(profile);
+    args.rpc ??= await getRpcUrl(profile);
+    const { tx, configPath, srcDir, rpc } = args;
+
+    const existingContracts = getExistingContracts(srcDir);
+
+    // Load the config
+    const mudConfig = (await loadConfig(configPath)) as StoreConfig & WorldConfig;
+
+    const resolvedConfig = resolveWorldConfig(
+      mudConfig,
+      existingContracts.map(({ basename }) => basename)
+    );
+
+    // Get worldAddress either from args or from worldsFile
+    const worldAddress = args.worldAddress ?? (await getWorldAddress(mudConfig.worldsFile, rpc));
+
+    // Create World contract instance from deployed address
+    const provider = new ethers.providers.StaticJsonRpcProvider(rpc);
+    const WorldContract = new ethers.Contract(worldAddress, IBaseWorldData.abi, provider) as IBaseWorld;
+
+    // TODO account for multiple namespaces (https://github.com/latticexyz/mud/issues/994)
+    const namespace = mudConfig.namespace;
+    const names = Object.values(resolvedConfig.systems).map(({ name }) => name);
+
+    const labels: { name: string; address: string }[] = [];
+    for (const name of names) {
+      const systemSelector = new TableId(namespace, name);
+      // Get the first field of `Systems` table (the table maps system name to its address and other data)
+      const address = await WorldContract.getField(systemsTableId.toHex(), [systemSelector.toHex()], 0);
+      labels.push({ name, address });
+    }
+
+    const result = await cast([
+      "run",
+      "--label",
+      `${worldAddress}:World`,
+      ...labels.map(({ name, address }) => ["--label", `${address}:${name}`]).flat(),
+      `${tx}`,
+    ]);
+    console.log(result);
+
+    process.exit(0);
+  },
+};
+
+export default commandModule;
+
+async function getWorldAddress(worldsFile: string, rpc: string) {
+  if (existsSync(worldsFile)) {
+    const chainId = await getChainId(rpc);
+    const deploys = JSON.parse(readFileSync(worldsFile, "utf-8"));
+
+    if (!deploys[chainId]) {
+      throw new MUDError(`chainId ${chainId} is missing in worldsFile "${worldsFile}"`);
+    }
+    return deploys[chainId].address as string;
+  } else {
+    throw new MUDError("worldAddress is not specified and worldsFile is missing");
+  }
+}

package/src/commands/tsgen.ts

@@ -0,0 +1,34 @@
+import type { CommandModule } from "yargs";
+import { loadConfig } from "@latticexyz/config/node";
+import { StoreConfig } from "@latticexyz/store";
+import { tsgen } from "../render-ts/tsgen";
+
+type Options = {
+  configPath: string;
+  out: string;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "tsgen",
+
+  describe: "Autogenerate MUD typescript definitions based on the config file",
+
+  builder(yargs) {
+    return yargs.options({
+      configPath: { type: "string", demandOption: true, desc: "Path to the config file" },
+      out: { type: "string", demandOption: true, desc: "Directory to output MUD typescript definition files" },
+    });
+  },
+
+  async handler(args) {
+    const { configPath, out } = args;
+
+    const config = (await loadConfig(configPath)) as StoreConfig;
+
+    await tsgen(config, out);
+
+    process.exit(0);
+  },
+};
+
+export default commandModule;

package/src/commands/worldgen.ts

@@ -0,0 +1,57 @@
+import type { CommandModule } from "yargs";
+import { loadConfig } from "@latticexyz/config/node";
+import { StoreConfig } from "@latticexyz/store";
+import { WorldConfig } from "@latticexyz/world";
+import { worldgen } from "@latticexyz/world/node";
+import { getSrcDirectory } from "@latticexyz/common/foundry";
+import path from "path";
+import { rmSync } from "fs";
+import { getExistingContracts } from "../utils";
+
+type Options = {
+  configPath?: string;
+  clean?: boolean;
+  srcDir?: string;
+  config?: StoreConfig & WorldConfig;
+};
+
+const commandModule: CommandModule<Options, Options> = {
+  command: "worldgen",
+
+  describe: "Autogenerate interfaces for Systems and World based on existing contracts and the config file",
+
+  builder(yargs) {
+    return yargs.options({
+      configPath: { type: "string", desc: "Path to the config file" },
+      clean: {
+        type: "boolean",
+        desc: "Clear the worldgen directory before generating new interfaces (defaults to true)",
+        default: true,
+      },
+    });
+  },
+
+  async handler(args) {
+    await worldgenHandler(args);
+    process.exit(0);
+  },
+};
+
+export async function worldgenHandler(args: Options) {
+  const srcDir = args.srcDir ?? (await getSrcDirectory());
+
+  const existingContracts = getExistingContracts(srcDir);
+
+  // Load the config
+  const mudConfig = args.config ?? ((await loadConfig(args.configPath)) as StoreConfig & WorldConfig);
+
+  const outputBaseDirectory = path.join(srcDir, mudConfig.codegenDirectory);
+
+  // clear the worldgen directory
+  if (args.clean) rmSync(path.join(outputBaseDirectory, mudConfig.worldgenDirectory), { recursive: true, force: true });
+
+  // generate new interfaces
+  await worldgen(mudConfig, existingContracts, outputBaseDirectory);
+}
+
+export default commandModule;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./render-ts";
+export * from "./utils/deployHandler";

package/src/modules.d.ts

@@ -0,0 +1,11 @@
+// adding .js to minimal would break clients down the line because it probably won't get a synthetic default import
+/* eslint-disable @typescript-eslint/no-explicit-any */
+declare module "protobufjs/minimal" {
+  export const configure: any;
+  export const util: any;
+  export const Reader: any;
+  export type Reader = any;
+  export const Writer: any;
+  export type Writer = any;
+}
+declare module "rollup-plugin-preserve-shebang";

package/src/mud.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { commands } from "./commands";
+import { logError } from "./utils/errors";
+
+// Load .env file into process.env
+import * as dotenv from "dotenv";
+import chalk from "chalk";
+dotenv.config();
+
+yargs(hideBin(process.argv))
+  // Explicit name to display in help (by default it's the entry file, which may not be "mud" for e.g. ts-node)
+  .scriptName("mud")
+  // Use the commands directory to scaffold
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- command array overload isn't typed, see https://github.com/yargs/yargs/blob/main/docs/advanced.md#esm-hierarchy
+  .command(commands as any)
+  // Enable strict mode.
+  .strict()
+  // Custom error handler
+  .fail((msg, err) => {
+    console.error(chalk.red(msg));
+    if (msg.includes("Missing required argument")) {
+      console.log(
+        chalk.yellow(`Run 'pnpm mud ${process.argv[2]} --help' for a list of available and required arguments.`)
+      );
+    }
+    console.log("");
+    logError(err);
+    console.log("");
+
+    process.exit(1);
+  })
+  // Useful aliases.
+  .alias({ h: "help" }).argv;

package/src/render-ts/index.ts

@@ -0,0 +1,5 @@
+export * from "./recsV1TableOptions.js";
+export * from "./renderRecsV1Tables.js";
+export * from "./schemaTypesToRecsTypeStrings.js";
+export * from "./tsgen.js";
+export * from "./types.js";

package/src/render-ts/recsV1TableOptions.ts

@@ -0,0 +1,39 @@
+import { StoreConfig } from "@latticexyz/store";
+import { resolveAbiOrUserType } from "@latticexyz/store/codegen";
+import { schemaTypesToRecsTypeStrings } from "./schemaTypesToRecsTypeStrings";
+import { RecsV1TableOptions } from "./types";
+
+export function getRecsV1TableOptions(config: StoreConfig): RecsV1TableOptions {
+  const tableOptions = [];
+  for (const tableName of Object.keys(config.tables)) {
+    const tableData = config.tables[tableName];
+
+    const fields = Object.keys(tableData.schema).map((name) => {
+      const abiOrUserType = tableData.schema[name];
+      const { schemaType } = resolveAbiOrUserType(abiOrUserType, config);
+
+      const recsTypeString = schemaTypesToRecsTypeStrings[schemaType];
+
+      return {
+        recsTypeString,
+        name,
+      };
+    });
+
+    // WARNING: skip tables without a static tableId
+    if (tableData.tableIdArgument) continue;
+    const staticResourceData = {
+      namespace: config.namespace,
+      name: tableData.name,
+    };
+
+    tableOptions.push({
+      tableName,
+      fields,
+      staticResourceData,
+    });
+  }
+  return {
+    tables: tableOptions,
+  };
+}

package/src/render-ts/renderRecsV1Tables.ts

@@ -0,0 +1,31 @@
+import { RecsV1TableOptions } from "./types";
+
+export function renderRecsV1Tables(options: RecsV1TableOptions) {
+  const { tables } = options;
+
+  return `/* Autogenerated file. Do not edit manually. */
+
+import { TableId } from "@latticexyz/common";
+import { defineComponent, Type as RecsType, World } from "@latticexyz/recs";
+
+export function defineContractComponents(world: World) {
+  return {
+    ${tables.map((table) => `${table.tableName}: ${renderDefineComponent(table)},`).join("")}
+  }
+}
+`;
+}
+
+function renderDefineComponent(table: RecsV1TableOptions["tables"][number]) {
+  const { namespace, name } = table.staticResourceData;
+  return `
+    (() => {
+      const tableId = new TableId("${namespace}", "${name}");
+      return defineComponent(world, {
+        ${table.fields.map(({ name, recsTypeString }) => `${name}: ${recsTypeString},`).join("")}
+      }, {
+        metadata: { contractId: tableId.toHex(), tableId: tableId.toString() },
+      });
+    })()
+  `;
+}