feat: return runtime versions used by the application with a doctor hook

src/README.md

@@ -27,15 +27,16 @@ invoked.
 
 ## Supported Scripts
 
-The hooks currently provided by this repo are `build`, `start`, `check-update`,
-`install-update`, `get-trigger`, and `get-manifest`.
+The hooks currently provided by this repo are `build`, `check-update`, `doctor`,
+`get-hooks`, `get-manifest`, `get-trigger`, `install-update`, and `start`.
 
 | Hook Name        | CLI Command            | Description                                                                                                                                                                                                                                                                                                                                                                                      |
 | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `build`          | `slack deploy`         | Bundles any functions with Deno into an output directory that's compatible with the Run on Slack runtime. Implemented in `build.ts`.                                                                                                                                                                                                                                                             |
 | `check-update`   | `slack upgrade`        | Checks the App's SDK dependencies to determine whether or not any of your libraries need to be updated. Implemented in `check_update.ts`.                                                                                                                                                                                                                                                        |
-| `get-manifest`   | `slack manifest`       | Converts a `manifest.json`, `manifest.js`, or `manifest.ts` file into a valid manifest JSON payload. Implemented in `get_manifest.ts`.                                                                                                                                                                                                                                                           |
+| `doctor`         | `slack doctor`         | Returns runtime versions and other system dependencies required by the application. Implemented in `doctor.ts`.                                                                                                                                                                                                                                                                                  |
 | `get-hooks`      | All                    | Fetches the list of available hooks for the CLI from this repository. Implemented in `mod.ts`.                                                                                                                                                                                                                                                                                                   |
+| `get-manifest`   | `slack manifest`       | Converts a `manifest.json`, `manifest.js`, or `manifest.ts` file into a valid manifest JSON payload. Implemented in `get_manifest.ts`.                                                                                                                                                                                                                                                           |
 | `get-trigger`    | `slack trigger create` | Converts a specified `json`, `js`, or `ts` file into a valid trigger JSON payload to be uploaded by the CLI to the `workflows.triggers.create` Slack API endpoint. Implemented in `get_trigger.ts`.                                                                                                                                                                                              |
 | `install-update` | `slack upgrade`        | Prompts the user to automatically update any dependencies that need to be updated based on the result of the `check-update` hook. Implemented in `install_update.ts`.                                                                                                                                                                                                                            |
 | `start`          | `slack run`            | While developing and locally running a deno-slack-based application, the CLI manages a socket connection with Slack's backend and delegates to this hook for invoking the correct application function for relevant events incoming via this connection. For more information, see the [deno-slack-runtime](https://github.com/slackapi/deno-slack-runtime) repository's details on `local-run`. |

src/check_update.ts

@@ -4,7 +4,7 @@ import {
   DENO_SLACK_SDK,
 } from "./libraries.ts";
 import { getProtocolInterface, JSONValue } from "./deps.ts";
-import { getJSON } from "./utilities.ts";
+import { getJSON, isNewSemverRelease } from "./utilities.ts";
 
 const IMPORT_MAP_SDKS = [DENO_SLACK_SDK, DENO_SLACK_API];
 const SLACK_JSON_SDKS = [
@@ -229,8 +229,10 @@ export async function fetchLatestModuleVersion(
 }
 
 /**
- * extractVersion takes in a string, searches for a version,
+ * extractVersion takes in a URL formatted string, searches for a version,
  * and, if version is found, returns that version.
+ *
+ * Example input: https://deno.land/x/[email protected]/
  */
 export function extractVersion(str: string): string {
   const at = str.indexOf("@");
@@ -245,26 +247,6 @@ export function extractVersion(str: string): string {
   return version;
 }
 
-/**
- * isNewSemverRelease takes two semver formatted strings
- * and compares them to see if the second argument is a
- * newer version than the first argument.
- * If it's newer it returns true, otherwise returns false.
- */
-
-export const isNewSemverRelease = (current: string, target: string) => {
-  const [currMajor, currMinor, currPatch] = current
-    .split(".")
-    .map((val) => Number(val));
-  const [targetMajor, targetMinor, targetPatch] = target
-    .split(".")
-    .map((val) => Number(val));
-
-  if (targetMajor !== currMajor) return targetMajor > currMajor;
-  if (targetMinor !== currMinor) return targetMinor > currMinor;
-  return targetPatch > currPatch;
-};
-
 /**
  * hasBreakingChange determines whether or not there is a
  * major version difference of greater or equal to 1 between the current

src/doctor.ts

@@ -0,0 +1,80 @@
+import { getProtocolInterface } from "./deps.ts";
+import { isNewSemverRelease } from "./utilities.ts";
+
+type RuntimeVersion = {
+  name: string;
+  current: string;
+} & RuntimeDetails;
+
+type RuntimeDetails = {
+  message?: string;
+  error?: {
+    message: string;
+  };
+};
+
+const getHostedDenoRuntimeVersion = async (): Promise<RuntimeDetails> => {
+  try {
+    const metadataURL = "https://api.slack.com/slackcli/metadata.json";
+    const response = await fetch(metadataURL);
+    if (!response.ok || response.status !== 200) {
+      throw new Error(
+        `Failed to collect upstream CLI metadata - ${response.status}`,
+      );
+    }
+    const metadata = await response.json();
+    const version = metadata?.["deno-runtime"]?.releases[0]?.version;
+    if (!version) {
+      const details = JSON.stringify(metadata, null, "  ");
+      return {
+        message: `Upstream CLI metadata response included:\n${details}`,
+        error: {
+          message: "Failed to find the minimum Deno version",
+        },
+      };
+    }
+    const message = Deno.version.deno !== version
+      ? `Applications deployed to Slack use Deno version ${version}`
+      : undefined;
+    if (isNewSemverRelease(Deno.version.deno, version)) {
+      return {
+        message,
+        error: { message: "The installed runtime version is not supported" },
+      };
+    }
+    return { message };
+  } catch (err) {
+    if (err instanceof Error) {
+      return { error: { message: err.message } };
+    }
+    return { error: { message: err } };
+  }
+};
+
+export const getRuntimeVersions = async (): Promise<{
+  versions: RuntimeVersion[];
+}> => {
+  const hostedDenoRuntimeVersion = await getHostedDenoRuntimeVersion();
+  const versions = [
+    {
+      "name": "deno",
+      "current": Deno.version.deno,
+      ...hostedDenoRuntimeVersion,
+    },
+    {
+      "name": "typescript",
+      "current": Deno.version.typescript,
+    },
+    {
+      "name": "v8",
+      "current": Deno.version.v8,
+    },
+  ];
+  return { versions };
+};
+
+if (import.meta.main) {
+  const protocol = getProtocolInterface(Deno.args);
+  const prunedDoctor = await getRuntimeVersions();
+  protocol.respond(JSON.stringify(prunedDoctor));
+}

src/mod.ts

@@ -18,6 +18,8 @@ export const projectScripts = (args: string[]) => {
         `deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/${HOOKS_TAG}/check_update.ts`,
       "install-update":
         `deno run -q --config=deno.jsonc --allow-run --allow-read --allow-write --allow-net https://deno.land/x/${HOOKS_TAG}/install_update.ts`,
+      "doctor":
+        `deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/${HOOKS_TAG}/doctor.ts`,
     },
     "config": {
       "protocol-version": ["message-boundaries"],

src/tests/check_update_test.ts

@@ -8,7 +8,6 @@ import {
   fetchLatestModuleVersion,
   getDenoImportMapFiles,
   hasBreakingChange,
-  isNewSemverRelease,
   readProjectDependencies,
 } from "../check_update.ts";
 
@@ -110,13 +109,13 @@ Deno.test("check-update hook tests", async (t) => {
   await t.step("extractDependencies method", async (evT) => {
     await evT.step(
       "given import_map.json or slack.json file contents, an array of key, value dependency pairs is returned",
-      async () => {
-        const importMapActual = await extractDependencies(
+      () => {
+        const importMapActual = extractDependencies(
           JSON.parse(MOCK_IMPORT_MAP_JSON),
           "imports",
         );
 
-        const slackHooksActual = await extractDependencies(
+        const slackHooksActual = extractDependencies(
           JSON.parse(MOCK_SLACK_JSON),
           "hooks",
         );
@@ -321,45 +320,4 @@ Deno.test("check-update hook tests", async (t) => {
       },
     );
   });
-  await t.step("isNewSemverRelease method", async (evT) => {
-    await evT.step("returns true for semver updates", () => {
-      assertEquals(isNewSemverRelease("0.0.1", "0.0.2"), true);
-      assertEquals(isNewSemverRelease("0.0.1", "0.2.0"), true);
-      assertEquals(isNewSemverRelease("0.0.1", "2.0.0"), true);
-      assertEquals(isNewSemverRelease("0.1.0", "0.1.1"), true);
-      assertEquals(isNewSemverRelease("0.1.0", "0.2.0"), true);
-      assertEquals(isNewSemverRelease("0.1.0", "2.0.0"), true);
-      assertEquals(isNewSemverRelease("1.0.0", "1.0.1"), true);
-      assertEquals(isNewSemverRelease("1.0.0", "1.1.0"), true);
-      assertEquals(isNewSemverRelease("1.0.0", "1.1.1"), true);
-      assertEquals(isNewSemverRelease("1.0.0", "2.0.0"), true);
-      assertEquals(isNewSemverRelease("0.0.2", "0.0.13"), true);
-    });
-    await evT.step("returns false for semver downgrades", () => {
-      assertEquals(isNewSemverRelease("2.0.0", "1.0.0"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "0.1.0"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "0.3.0"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "0.0.1"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "0.0.3"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "1.1.0"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "1.3.0"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "1.1.1"), false);
-      assertEquals(isNewSemverRelease("2.0.0", "1.3.3"), false);
-      assertEquals(isNewSemverRelease("0.2.0", "0.1.0"), false);
-      assertEquals(isNewSemverRelease("0.2.0", "0.0.1"), false);
-      assertEquals(isNewSemverRelease("0.2.0", "0.0.3"), false);
-      assertEquals(isNewSemverRelease("0.2.0", "0.1.1"), false);
-      assertEquals(isNewSemverRelease("0.2.0", "0.1.3"), false);
-      assertEquals(isNewSemverRelease("0.0.2", "0.0.1"), false);
-      assertEquals(isNewSemverRelease("0.0.20", "0.0.13"), false);
-    });
-    await evT.step("returns false for semver matches", () => {
-      assertEquals(isNewSemverRelease("0.0.1", "0.0.1"), false);
-      assertEquals(isNewSemverRelease("0.1.0", "0.1.0"), false);
-      assertEquals(isNewSemverRelease("0.1.1", "0.1.1"), false);
-      assertEquals(isNewSemverRelease("1.0.0", "1.0.0"), false);
-      assertEquals(isNewSemverRelease("1.0.1", "1.0.1"), false);
-      assertEquals(isNewSemverRelease("1.1.1", "1.1.1"), false);
-    });
-  });
 });

src/tests/doctor_test.ts

@@ -0,0 +1,169 @@
+import { assertEquals } from "../dev_deps.ts";
+import { mockFetch } from "../dev_deps.ts";
+import { getRuntimeVersions } from "../doctor.ts";
+
+const REAL_DENO_VERSION = Deno.version;
+const MOCK_DENO_VERSION = {
+  deno: "1.2.3",
+  typescript: "5.0.0",
+  v8: "12.3.456.78",
+};
+
+const MOCK_SLACK_CLI_MANIFEST = {
+  "slack-cli": {
+    "title": "Slack CLI",
+    "description": "CLI for creating, building, and deploying Slack apps.",
+    "releases": [
+      {
+        "version": "2.19.0",
+        "release_date": "2024-03-11",
+      },
+    ],
+  },
+  "deno-runtime": {
+    "title": "Deno Runtime",
+    "releases": [
+      {
+        "version": "1.101.1",
+        "release_date": "2023-09-19",
+      },
+    ],
+  },
+};
+
+Deno.test("doctor hook tests", async (t) => {
+  Object.defineProperty(Deno, "version", {
+    value: MOCK_DENO_VERSION,
+    writable: true,
+    configurable: true,
+  });
+  mockFetch.install();
+
+  await t.step("known runtime values for the system are returned", async () => {
+    mockFetch.mock("GET@/slackcli/metadata.json", (_req: Request) => {
+      return new Response(null, { status: 404 });
+    });
+    Deno.version.deno = "1.2.3";
+
+    const actual = await getRuntimeVersions();
+    const expected = {
+      versions: [
+        {
+          name: "deno",
+          current: "1.2.3",
+          error: {
+            message: "Failed to collect upstream CLI metadata - 404",
+          },
+        },
+        {
+          name: "typescript",
+          current: "5.0.0",
+        },
+        {
+          name: "v8",
+          current: "12.3.456.78",
+        },
+      ],
+    };
+    assertEquals(actual, expected);
+  });
+
+  await t.step("matched upstream requirements return success", async () => {
+    mockFetch.mock("GET@/slackcli/metadata.json", (_req: Request) => {
+      return new Response(JSON.stringify(MOCK_SLACK_CLI_MANIFEST));
+    });
+    Deno.version.deno = "1.101.1";
+
+    const actual = await getRuntimeVersions();
+    const expected = {
+      versions: [
+        {
+          name: "deno",
+          current: "1.101.1",
+          message: undefined,
+        },
+        {
+          name: "typescript",
+          current: "5.0.0",
+        },
+        {
+          name: "v8",
+          current: "12.3.456.78",
+        },
+      ],
+    };
+    assertEquals(actual, expected);
+  });
+
+  await t.step("unsupported upstream runtimes note differences", async () => {
+    mockFetch.mock("GET@/slackcli/metadata.json", (_req: Request) => {
+      return new Response(JSON.stringify(MOCK_SLACK_CLI_MANIFEST));
+    });
+    Deno.version.deno = "1.2.3";
+
+    const actual = await getRuntimeVersions();
+    const expected = {
+      versions: [
+        {
+          name: "deno",
+          current: "1.2.3",
+          message: "Applications deployed to Slack use Deno version 1.101.1",
+          error: {
+            message: "The installed runtime version is not supported",
+          },
+        },
+        {
+          name: "typescript",
+          current: "5.0.0",
+        },
+        {
+          name: "v8",
+          current: "12.3.456.78",
+        },
+      ],
+    };
+    assertEquals(actual, expected);
+  });
+
+  await t.step("missing minimums from cli metadata are noted", async () => {
+    const metadata = {
+      runtimes: ["deno", "node"],
+    };
+    mockFetch.mock("GET@/slackcli/metadata.json", (_req: Request) => {
+      return new Response(JSON.stringify(metadata));
+    });
+    Deno.version.deno = "1.2.3";
+
+    const actual = await getRuntimeVersions();
+    const expected = {
+      versions: [
+        {
+          name: "deno",
+          current: "1.2.3",
+          message: `Upstream CLI metadata response included:\n${
+            JSON.stringify(metadata, null, 2)
+          }`,
+          error: {
+            message: "Failed to find the minimum Deno version",
+          },
+        },
+        {
+          name: "typescript",
+          current: "5.0.0",
+        },
+        {
+          name: "v8",
+          current: "12.3.456.78",
+        },
+      ],
+    };
+    assertEquals(actual, expected);
+  });
+
+  Object.defineProperty(Deno, "version", {
+    value: REAL_DENO_VERSION,
+    writable: false,
+    configurable: false,
+  });
+  mockFetch.uninstall();
+});