add builtin task to run hardhat scripts

Author: zoeyTM

v-next/hardhat-errors/src/descriptors.ts

@@ -640,6 +640,22 @@ The first supported version is {firstSupportedVersion}`,
 Please use a newer, supported version.`,
       shouldBeReported: true,
     },
+    RUN_FILE_NOT_FOUND: {
+      number: 603,
+      messageTemplate: `Script {script} doesn't exist`,
+      websiteTitle: "Script doesn't exist",
+      websiteDescription: `Tried to use \`hardhat run\` to execute a nonexistent script.
+
+Please double check your script's path.`,
+    },
+    RUN_SCRIPT_ERROR: {
+      number: 604,
+      messageTemplate: `Error running script {script}: {error}`,
+      websiteTitle: "Error running script",
+      websiteDescription: `Running a script resulted in an error.
+
+Please check Hardhat's output for more details.`,
+    },
   },
   ARTIFACTS: {
     NOT_FOUND: {

v-next/hardhat/src/internal/builtin-plugins/index.ts

@@ -1,5 +1,6 @@
 import type { HardhatPlugin } from "@nomicfoundation/hardhat-core/types/plugins";
 
 import hardhatFoo from "./hardhat-foo/index.js";
+import run from "./run/index.js";
 
-export const builtinPlugins: HardhatPlugin[] = [hardhatFoo];
+export const builtinPlugins: HardhatPlugin[] = [hardhatFoo, run];

v-next/hardhat/src/internal/builtin-plugins/run/index.ts

@@ -0,0 +1,23 @@
+import type { HardhatPlugin } from "@nomicfoundation/hardhat-core/types/plugins";
+
+import { ParameterType, task } from "@nomicfoundation/hardhat-core/config";
+
+import { runScriptWithHardhat } from "./runScriptWithHardhat.js";
+
+export default {
+  id: "run",
+  tasks: [
+    task("run", "Runs a user-defined script after compiling the project")
+      .addPositionalParameter({
+        name: "script",
+        description: "A js or ts file to be run within hardhat's environment",
+        type: ParameterType.STRING,
+      })
+      .addFlag({
+        name: "noCompile",
+        description: "Don't compile before running this task",
+      })
+      .setAction(runScriptWithHardhat)
+      .build(),
+  ],
+} satisfies HardhatPlugin;

v-next/hardhat/src/internal/builtin-plugins/run/runScriptWithHardhat.ts

@@ -0,0 +1,54 @@
+import type { NewTaskActionFunction } from "@nomicfoundation/hardhat-core/types/tasks";
+
+import path from "node:path";
+
+import {
+  HardhatError,
+  assertHardhatInvariant,
+} from "@nomicfoundation/hardhat-errors";
+import { exists } from "@nomicfoundation/hardhat-utils/fs";
+
+export const runScriptWithHardhat: NewTaskActionFunction = async (
+  { script, noCompile },
+  _hre,
+) => {
+  assertHardhatInvariant(
+    typeof script === "string",
+    "Expected script to be a string",
+  );
+
+  assertHardhatInvariant(
+    typeof noCompile === "boolean",
+    "Expected noCompile to be a boolean",
+  );
+
+  const scriptPath = path.resolve(process.cwd(), script);
+
+  if (!(await exists(scriptPath))) {
+    throw new HardhatError(
+      HardhatError.ERRORS.BUILTIN_TASKS.RUN_FILE_NOT_FOUND,
+      { script },
+    );
+  }
+
+  if (!noCompile) {
+    // todo: run compile task
+  }
+
+  try {
+    await import(scriptPath);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new HardhatError(
+        HardhatError.ERRORS.BUILTIN_TASKS.RUN_SCRIPT_ERROR,
+        {
+          script,
+          error: error.message,
+        },
+        error,
+      );
+    }
+
+    throw error;
+  }
+};

v-next/hardhat/test/fixture-projects/run-script-js/hardhat.config.js

@@ -0,0 +1,11 @@
+import { task } from "@nomicfoundation/hardhat/config";
+
+export default {
+  tasks: [
+    task("test", "Prints a test")
+      .setAction(async () => {
+        console.log("test!");
+      })
+      .build(),
+  ],
+};

v-next/hardhat/test/fixture-projects/run-script-js/scripts/success.js

@@ -0,0 +1,5 @@
+import hre from "@nomicfoundation/hardhat";
+
+if (!hre.tasks.rootTasks.has("test")) {
+  throw new Error("test task not found");
+}

v-next/hardhat/test/fixture-projects/run-script-js/scripts/throws.js

@@ -0,0 +1 @@
+throw new Error("broken script");

v-next/hardhat/test/fixture-projects/run-ts-script/hardhat.config.ts

@@ -0,0 +1,11 @@
+import { task } from "@nomicfoundation/hardhat/config";
+
+export default {
+  tasks: [
+    task("test", "Prints a test")
+      .setAction(async () => {
+        console.log("test!");
+      })
+      .build(),
+  ],
+};

v-next/hardhat/test/fixture-projects/run-ts-script/scripts/success.ts

@@ -0,0 +1,5 @@
+import hre from "@nomicfoundation/hardhat";
+
+if (!hre.tasks.rootTasks.has("test")) {
+  throw new Error("test task not found");
+}

v-next/hardhat/test/fixture-projects/run-ts-script/scripts/throws.ts

@@ -0,0 +1 @@
+throw new Error("broken script");

v-next/hardhat/test/internal/builtin-plugins/run/runScriptWIthHardhat.ts

@@ -0,0 +1,110 @@
+import type { HardhatRuntimeEnvironment } from "@nomicfoundation/hardhat-core/types/hre";
+
+import assert from "node:assert/strict";
+import { before, describe, it } from "node:test";
+
+import { createHardhatRuntimeEnvironment } from "@nomicfoundation/hardhat-core";
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+
+import { runScriptWithHardhat } from "../../../../src/internal/builtin-plugins/run/runScriptWithHardhat.js";
+import { useFixtureProject } from "../../../helpers/project.js";
+
+describe("runScriptWithHardhat", function () {
+  let hre: HardhatRuntimeEnvironment;
+
+  before(async function () {
+    hre = await createHardhatRuntimeEnvironment({});
+  });
+
+  it("should throw if script is not a string", async function () {
+    await assert.rejects(async () => {
+      await runScriptWithHardhat({ script: 123, noCompile: false }, hre);
+    }, /An internal invariant was violated: Expected script to be a string/);
+  });
+
+  it("should throw if noCompile is not a boolean", async function () {
+    await assert.rejects(async () => {
+      await runScriptWithHardhat({ script: "script.js", noCompile: 123 }, hre);
+    }, /An internal invariant was violated: Expected noCompile to be a boolean/);
+  });
+
+  describe("javascript", function () {
+    useFixtureProject("run-js-script");
+
+    it("should throw if script does not exist", async function () {
+      await assert.rejects(
+        async () => {
+          await runScriptWithHardhat(
+            { script: "./scripts/non-existent.js", noCompile: false },
+            hre,
+          );
+        },
+        new HardhatError(HardhatError.ERRORS.BUILTIN_TASKS.RUN_FILE_NOT_FOUND, {
+          script: "./scripts/non-existent.js",
+        }),
+      );
+    });
+
+    it("should run a script successfully", async function () {
+      await runScriptWithHardhat(
+        { script: "./scripts/success.js", noCompile: false },
+        hre,
+      );
+    });
+
+    it("should throw if the script throws", async function () {
+      await assert.rejects(
+        async () => {
+          await runScriptWithHardhat(
+            { script: "./scripts/throws.js", noCompile: false },
+            hre,
+          );
+        },
+        new HardhatError(HardhatError.ERRORS.BUILTIN_TASKS.RUN_SCRIPT_ERROR, {
+          script: "./scripts/throws.js",
+          error: "broken script",
+        }),
+      );
+    });
+  });
+
+  describe("typescript", function () {
+    useFixtureProject("run-ts-script");
+
+    it("should throw if script does not exist", async function () {
+      await assert.rejects(
+        async () => {
+          await runScriptWithHardhat(
+            { script: "./scripts/non-existent.ts", noCompile: false },
+            hre,
+          );
+        },
+        new HardhatError(HardhatError.ERRORS.BUILTIN_TASKS.RUN_FILE_NOT_FOUND, {
+          script: "./scripts/non-existent.ts",
+        }),
+      );
+    });
+
+    it("should run a script successfully", async function () {
+      await runScriptWithHardhat(
+        { script: "./scripts/success.ts", noCompile: false },
+        hre,
+      );
+    });
+
+    it("should throw if the script throws", async function () {
+      await assert.rejects(
+        async () => {
+          await runScriptWithHardhat(
+            { script: "./scripts/throws.ts", noCompile: false },
+            hre,
+          );
+        },
+        new HardhatError(HardhatError.ERRORS.BUILTIN_TASKS.RUN_SCRIPT_ERROR, {
+          script: "./scripts/throws.ts",
+          error: "broken script",
+        }),
+      );
+    });
+  });
+});