Merge pull request #273 from coder/mes/readme-update

fix: add missing README information and clean up types

Author: Parkreiner

CONTRIBUTING.md

@@ -1,24 +1,47 @@
 # Contributing
 
-To create a new module, clone this repository and run:
+## Getting started
+
+This repo uses the [Bun runtime](https://bun.sh/) to to run all code and tests. To install Bun, you can run this command on Linux/MacOS:
+
+```shell
+curl -fsSL https://bun.sh/install | bash
+```
+
+Or this command on Windows:
 
 ```shell
-./new.sh MODULE_NAME
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+Follow the instructions to ensure that Bun is available globally. Once Bun has been installed, clone this repository. From there, run this script to create a new module:
+
+```shell
+./new.sh NAME_OF_NEW_MODULE
 ```
 
 ## Testing a Module
 
+> **Note:** It is the responsibility of the module author to implement tests for their module. The author must test the module locally before submitting a PR.
+
 A suite of test-helpers exists to run `terraform apply` on modules with variables, and test script output against containers.
 
-The testing suite must be able to run docker containers with the `--network=host` flag, which typically requires running the tests on Linux as this flag does not apply to Docker Desktop for MacOS and Windows. MacOS users can work around this by using something like [colima](https://github.com/abiosoft/colima) or [Orbstack](https://orbstack.dev/) instead of Docker Desktop.
+The testing suite must be able to run docker containers with the `--network=host` flag. This typically requires running the tests on Linux as this flag does not apply to Docker Desktop for MacOS and Windows. MacOS users can work around this by using something like [colima](https://github.com/abiosoft/colima) or [Orbstack](https://orbstack.dev/) instead of Docker Desktop.
+
+Reference the existing `*.test.ts` files to get an idea for how to set up tests.
 
-Reference existing `*.test.ts` files for implementation.
+You can run all tests in a specific file with this command:
 
 ```shell
-# Run tests for a specific module!
 $ bun test -t '<module>'
 ```
 
+Or run all tests by running this command:
+
+```shell
+$ bun test
+```
+
 You can test a module locally by updating the source as follows
 
 ```tf
@@ -27,4 +50,25 @@ module "example" {
 }
 ```
 
-> **Note:** This is the responsibility of the module author to implement tests for their module. and test the module locally before submitting a PR.
+## Releases
+
+> [!WARNING]
+> When creating a new release, make sure that your new version number is fully accurate. If a version number is incorrect or does not exist, we may end up serving incorrect/old data for our various tools and providers.
+
+Much of our release process is automated. To cut a new release:
+
+1. Navigate to [GitHub's Releases page](https://github.com/coder/modules/releases)
+2. Click "Draft a new release"
+3. Click the "Choose a tag" button and type a new release number in the format `v<major>.<minor>.<patch>` (e.g., `v1.18.0`). Then click "Create new tag".
+4. Click the "Generate release notes" button, and clean up the resulting README. Be sure to remove any notes that would not be relevant to end-users (e.g., bumping dependencies).
+5. Once everything looks good, click the "Publish release" button.
+
+Once the release has been cut, a script will run to check whether there are any modules that will require that the new release number be published to Terraform. If there are any, a new pull request will automatically be generated. Be sure to approve this PR and merge it into the `main` branch.
+
+Following that, our automated processes will handle publishing new data for [`registry.coder.com`](https://github.com/coder/registry.coder.com/):
+
+1. Publishing new versions to Coder's [Terraform Registry](https://registry.terraform.io/providers/coder/coder/latest)
+2. Publishing new data to the [Coder Registry](https://registry.coder.com)
+
+> [!NOTE]
+> Some data in `registry.coder.com` is fetched on demand from the Module repo's main branch. This data should be updated almost immediately after a new release, but other changes will take some time to propagate.

README.md

@@ -3,14 +3,14 @@
   Modules
   </h1>
 
-[Registry](https://registry.coder.com) | [Coder Docs](https://coder.com/docs) | [Why Coder](https://coder.com/why) | [Coder Enterprise](https://coder.com/docs/v2/latest/enterprise)
+[Module Registry](https://registry.coder.com) | [Coder Docs](https://coder.com/docs) | [Why Coder](https://coder.com/why) | [Coder Enterprise](https://coder.com/docs/v2/latest/enterprise)
 
 [![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder)
 [![license](https://img.shields.io/github/license/coder/modules)](./LICENSE)
 
 </div>
 
-Modules extend Templates to create reusable components for your development environment.
+Modules extend Coder Templates to create reusable components for your development environment.
 
 e.g.
 

lint.ts

@@ -5,14 +5,15 @@ import grayMatter from "gray-matter";
 
 const files = await readdir(".", { withFileTypes: true });
 const dirs = files.filter(
-  (f) => f.isDirectory() && !f.name.startsWith(".") && f.name !== "node_modules"
+  (f) =>
+    f.isDirectory() && !f.name.startsWith(".") && f.name !== "node_modules",
 );
 
 let badExit = false;
 
 // error reports an error to the console and sets badExit to true
 // so that the process will exit with a non-zero exit code.
-const error = (...data: any[]) => {
+const error = (...data: unknown[]) => {
   console.error(...data);
   badExit = true;
 };
@@ -22,15 +23,20 @@ const verifyCodeBlocks = (
   res = {
     codeIsTF: false,
     codeIsHCL: false,
-  }
+  },
 ) => {
   for (const token of tokens) {
     // Check in-depth.
     if (token.type === "list") {
       verifyCodeBlocks(token.items, res);
       continue;
     }
+
     if (token.type === "list_item") {
+      if (token.tokens === undefined) {
+        throw new Error("Tokens are missing for type list_item");
+      }
+
       verifyCodeBlocks(token.tokens, res);
       continue;
     }
@@ -80,8 +86,9 @@ for (const dir of dirs) {
   if (!data.maintainer_github) {
     error(dir.name, "missing maintainer_github");
   }
+
   try {
-    await stat(path.join(".", dir.name, data.icon));
+    await stat(path.join(".", dir.name, data.icon ?? ""));
   } catch (ex) {
     error(dir.name, "icon does not exist", data.icon);
   }

slackme/main.test.ts

@@ -126,7 +126,10 @@ const assertSlackMessage = async (opts: {
   durationMS?: number;
   output: string;
 }) => {
-  let url: URL;
+  // Have to use non-null assertion because TS can't tell when the fetch
+  // function will run
+  let url!: URL;
+
   const fakeSlackHost = serve({
     fetch: (req) => {
       url = new URL(req.url);
@@ -138,22 +141,24 @@ const assertSlackMessage = async (opts: {
     },
     port: 0,
   });
+
   const { instance, id } = await setupContainer(
     "alpine/curl",
-    opts.format && {
-      slack_message: opts.format,
-    },
+    opts.format ? { slack_message: opts.format } : undefined,
   );
+
   await writeCoder(id, "echo 'token'");
   let exec = await execContainer(id, ["sh", "-c", instance.script]);
   expect(exec.exitCode).toBe(0);
+
   exec = await execContainer(id, [
     "sh",
     "-c",
     `DURATION_MS=${opts.durationMS || 0} SLACK_URL="http://${
       fakeSlackHost.hostname
     }:${fakeSlackHost.port}" slackme ${opts.command}`,
   ]);
+
   expect(exec.stderr.trim()).toBe("");
   expect(url.pathname).toEqual("/api/chat.postMessage");
   expect(url.searchParams.get("channel")).toEqual("token");

test.ts

@@ -90,17 +90,21 @@ type TerraformStateResource = {
   type: string;
   name: string;
   provider: string;
-  instances: [{ attributes: Record<string, any> }];
+
+  instances: [
+    {
+      attributes: Record<string, JsonValue>;
+    },
+  ];
 };
 
-export interface TerraformState {
-  outputs: {
-    [key: string]: {
-      type: string;
-      value: any;
-    };
-  };
+type TerraformOutput = {
+  type: string;
+  value: JsonValue;
+};
 
+export interface TerraformState {
+  outputs: Record<string, TerraformOutput>;
   resources: [TerraformStateResource, ...TerraformStateResource[]];
 }
 
@@ -149,19 +153,25 @@ export const testRequiredVariables = <TVars extends Record<string, string>>(
   it("required variables", async () => {
     await runTerraformApply(dir, vars);
   });
+
   const varNames = Object.keys(vars);
   varNames.forEach((varName) => {
     // Ensures that every variable provided is required!
     it("missing variable " + varName, async () => {
-      const localVars = {};
+      const localVars: Record<string, string> = {};
       varNames.forEach((otherVarName) => {
         if (otherVarName !== varName) {
           localVars[otherVarName] = vars[otherVarName];
         }
       });
+
       try {
         await runTerraformApply(dir, localVars);
       } catch (ex) {
+        if (!(ex instanceof Error)) {
+          throw new Error("Unknown error generated");
+        }
+
         expect(ex.message).toContain(
           `input variable \"${varName}\" is not set`,
         );

tsconfig.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "target": "esnext",
     "module": "esnext",
+    "strict": true,
     "allowSyntheticDefaultImports": true,
     "moduleResolution": "nodenext",
     "types": ["bun-types"]

vscode-desktop/main.test.ts

@@ -24,9 +24,10 @@ describe("vscode-desktop", async () => {
     const coder_app = state.resources.find(
       (res) => res.type == "coder_app" && res.name == "vscode",
     );
+
     expect(coder_app).not.toBeNull();
-    expect(coder_app.instances.length).toBe(1);
-    expect(coder_app.instances[0].attributes.order).toBeNull();
+    expect(coder_app?.instances.length).toBe(1);
+    expect(coder_app?.instances[0].attributes.order).toBeNull();
   });
 
   it("adds folder", async () => {
@@ -80,8 +81,9 @@ describe("vscode-desktop", async () => {
     const coder_app = state.resources.find(
       (res) => res.type == "coder_app" && res.name == "vscode",
     );
+
     expect(coder_app).not.toBeNull();
-    expect(coder_app.instances.length).toBe(1);
-    expect(coder_app.instances[0].attributes.order).toBe(22);
+    expect(coder_app?.instances.length).toBe(1);
+    expect(coder_app?.instances[0].attributes.order).toBe(22);
   });
 });

windows-rdp/main.test.ts

@@ -24,7 +24,10 @@ function findWindowsRdpScript(state: TerraformState): string | null {
     }
 
     for (const instance of resource.instances) {
-      if (instance.attributes.display_name === "windows-rdp") {
+      if (
+        instance.attributes.display_name === "windows-rdp" &&
+        typeof instance.attributes.script === "string"
+      ) {
         return instance.attributes.script;
       }
     }
@@ -100,11 +103,11 @@ describe("Web RDP", async () => {
     const defaultRdpScript = findWindowsRdpScript(defaultState);
     expect(defaultRdpScript).toBeString();
 
-    const { username: defaultUsername, password: defaultPassword } =
-      formEntryValuesRe.exec(defaultRdpScript)?.groups ?? {};
+    const defaultResultsGroup =
+      formEntryValuesRe.exec(defaultRdpScript ?? "")?.groups ?? {};
 
-    expect(defaultUsername).toBe("Administrator");
-    expect(defaultPassword).toBe("coderRDP!");
+    expect(defaultResultsGroup.username).toBe("Administrator");
+    expect(defaultResultsGroup.password).toBe("coderRDP!");
 
     // Test that custom usernames/passwords are also forwarded correctly
     const customAdminUsername = "crouton";
@@ -122,10 +125,10 @@ describe("Web RDP", async () => {
     const customRdpScript = findWindowsRdpScript(customizedState);
     expect(customRdpScript).toBeString();
 
-    const { username: customUsername, password: customPassword } =
-      formEntryValuesRe.exec(customRdpScript)?.groups ?? {};
+    const customResultsGroup =
+      formEntryValuesRe.exec(customRdpScript ?? "")?.groups ?? {};
 
-    expect(customUsername).toBe(customAdminUsername);
-    expect(customPassword).toBe(customAdminPassword);
+    expect(customResultsGroup.username).toBe(customAdminUsername);
+    expect(customResultsGroup.password).toBe(customAdminPassword);
   });
 });