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/doctor.ts

@@ -0,0 +1,66 @@
+import { getProtocolInterface } from "./deps.ts";
+
+type RuntimeVersion = {
+  name: string;
+  current: string;
+  minimum?: string;
+  error?: {
+    message: string;
+  };
+};
+
+const getHostedDenoRuntimeVersion = async (): Promise<{
+  minimum?: string;
+  message?: string;
+  error?: { message: string };
+}> => {
+  try {
+    const metadataURL = "https://api.slack.com/slackcli/metadata.json";
+    const response = await fetch(metadataURL);
+    if (!response.ok) {
+      throw new Error("Failed to collect upstream CLI metadata");
+    }
+    const metadata = await response.json();
+    const version = metadata?.["deno-runtime"]?.releases[0]?.version;
+    if (!version) {
+      throw new Error("Failed to find the minimum Deno version");
+    }
+    const message = Deno.version.deno !== version
+      ? `Applications deployed to Slack use Deno version ${version}`
+      : undefined;
+    return { minimum: version, 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/doctor_test.ts

@@ -0,0 +1,162 @@
+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",
+          },
+        },
+        {
+          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",
+          minimum: "1.101.1",
+          message: undefined,
+        },
+        {
+          name: "typescript",
+          current: "5.0.0",
+        },
+        {
+          name: "v8",
+          current: "12.3.456.78",
+        },
+      ],
+    };
+    assertEquals(actual, expected);
+  });
+
+  await t.step("mismatched upstream requirements note difference", 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",
+          minimum: "1.101.1",
+          message: "Applications deployed to Slack use Deno version 1.101.1",
+        },
+        {
+          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 () => {
+    mockFetch.mock("GET@/slackcli/metadata.json", (_req: Request) => {
+      return new Response(JSON.stringify({}));
+    });
+    Deno.version.deno = "1.2.3";
+
+    const actual = await getRuntimeVersions();
+    const expected = {
+      versions: [
+        {
+          name: "deno",
+          current: "1.2.3",
+          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();
+});