Add sandbox setup cmd for VSCodium

packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.md → packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.mdx

@@ -1,7 +1,9 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 # Contributing
 
-Welcome! So glad you've decided to help make Cursorless better. You'll want to start by getting [set up](#initial-setup) and learning how to [run / test a local copy of the
-extension](#running--testing-extension-locally). You may also find the [VSCode API docs](https://code.visualstudio.com/api) helpful to learn about VSCode extension development.
+Welcome! So glad you've decided to help make Cursorless better. You'll want to start by getting [set up](#initial-setup) and learning how to [run / test a local copy of the extension](#running--testing-extension-locally). You may also find the [VSCode API docs](https://code.visualstudio.com/api) helpful to learn about VSCode extension development.
 
 ## Initial setup
 
@@ -10,7 +12,8 @@ extension](#running--testing-extension-locally). You may also find the [VSCode A
 - [Git](https://git-scm.com/)
 - [Node.js](https://nodejs.org/en/)
 - [Corepack](https://nodejs.org/api/corepack.html) or [pnpm](https://pnpm.io/installation)
-- [VSCode](https://code.visualstudio.com/); minimum version for local development is 1.72.0 in order to support settings profiles for sandboxed development. Please file an issue if that is a problem.
+- [VSCode](https://code.visualstudio.com/) or [VSCodium](https://vscodium.com/)
+  Both VSCode and VSCodium will be referred to as VSCode except when instructions differ between the editors.
 
 ### Steps
 
@@ -23,25 +26,52 @@ extension](#running--testing-extension-locally). You may also find the [VSCode A
    pnpm compile
    ```
 
-4. Run
+4. Run the following in the terminal:
 
-   ```bash
-   code --profile=cursorlessDevelopment
-   ```
+   <Tabs groupId="vsx">
+     <TabItem value="vscode" label="VSCode" default>
+       `bash code --profile=cursorlessDevelopment`
+     </TabItem>
+     <TabItem value="vscodium" label="VSCodium">
+       `bash codium --profile=cursorlessDevelopment`
+     </TabItem>
+   </Tabs>
 
    and then close the window that opens (eg say `"window close"`). This step is necessary to create the [VSCode settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. Once https://github.com/microsoft/vscode/issues/172046 is resolved, we will be able to remove this step, as the profile can then automatically be created.
 
 5. Run the following in the terminal:
 
-   ```bash
-   pnpm init-vscode-sandbox
-   ```
-
-   The `pnpm init-vscode-sandbox` command creates a local [VSCode settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. This approach is [suggested](https://code.visualstudio.com/updates/v1_72#_extension-debugging-in-a-clean-environment) by the VSCode documentation. If you need to update any of the extension dependencies in the sandbox, you can add `--force` to the command. If you'd like to use additional extensions when debugging locally, you can use the following command:
-
-   ```bash
-   code --profile=cursorlessDevelopment --install-extension some.extension
-   ```
+   <Tabs groupId="vsx">
+     <TabItem value="vscode" label="VSCode">
+       ```bash pnpm init-vscode-sandbox```
+     </TabItem>
+     <TabItem value="vscodium" label="VSCodium">
+       `bash pnpm init-vscode-sandbox --codium` VSCodium users will also need to
+       manually download and install the `jrieken:vscode-tree-sitter-query`
+       extension, as it is [currently not
+       avalible](https://github.com/jrieken/vscode-tree-sitter-query/issues/28)
+       on the OpenVSX Marketplace. Instructions on how to manually download the
+       extension can be found [in this Stack Overflow
+       post](https://stackoverflow.com/a/79565372)
+       ([archived](https://web.archive.org/web/20250421130639/https://stackoverflow.com/questions/79359919/how-can-i-manually-download-vsix-files-now-that-the-vs-code-marketplace-no-long/79565372#79565372)),
+       while manual installation instructions can be found directly
+       below—replace `some.extension` with the acquired `.vsix` file's path
+       instead of an extension id.
+     </TabItem>
+   </Tabs>
+
+   Said command adds extensions to the aforementioned settings profile that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. This approach is [suggested](https://code.visualstudio.com/updates/v1_72#_extension-debugging-in-a-clean-environment) by the VSCode documentation. If you need to update any of the extension dependencies in the sandbox, you can add `--force` to the command. If you'd like to use additional extensions when debugging locally, you can use the following command:
+
+   <Tabs groupId="vsx">
+     <TabItem value="vscode" label="VSCode">
+       `bash code --profile=cursorlessDevelopment --install-extension
+       some.extension`
+     </TabItem>
+     <TabItem value="vscodium" label="VSCodium">
+       `bash codium --profile=cursorlessDevelopment --install-extension
+       some.extension`
+     </TabItem>
+   </Tabs>
 
    where `some.extension` is the id of the extension you'd like to install into the sandbox.
 
@@ -106,9 +136,15 @@ vsce package -o bundle.vsix
 
 Once you have your package then you can install it into the sandbox using the following command:
 
-```
-code --profile=cursorlessDevelopment --install-extension bundle.vsix
-```
+<Tabs groupId="vsx">
+  <TabItem value="vscode" label="VSCode">
+    `bash code --profile=cursorlessDevelopment --install-extension bundle.vsix`
+  </TabItem>
+  <TabItem value="vscodium" label="VSCodium">
+    `bash codium --profile=cursorlessDevelopment --install-extension
+    bundle.vsix`
+  </TabItem>
+</Tabs>
 
 ## Installing a local build of the Cursorless extension
 

packages/cursorless-org-docs/src/docs/contributing/cheatsheet.md

@@ -8,7 +8,7 @@ The implementation of the local version of the cheatsheet is split between the T
 
 When you add a new scope type, action, modifier, etc, you'll need to ensure that it shows up both locally and on the website. It will usually automatically show up in the local cheatsheet. You can verify this by saying `"cursorless cheatsheet"` with your development version of `cursorless-talon` active in your Talon user directory, and inspecting the cheatsheet that appears. If it does not, you'll need to make fixes to [the Talon side of the cheatsheet](../../../../../cursorless-talon/src/cheatsheet).
 
-In either case, to get your changes to appear on the website, you need to update the defaults in [`defaults.json`](../../../../../packages/cheatsheet/src/lib/sampleSpokenFormInfos/defaults.json). First make sure you have the `cursorless-talon-dev` user file set in your Talon home directory, as indicated in the [initial contributor setup instructions](CONTRIBUTING.md#initial-setup). Then you can say `"cursorless update cheatsheet"` to update the default spoken forms. Note that this will use your custom spoken forms, so you may need to do some manual cleanup.
+In either case, to get your changes to appear on the website, you need to update the defaults in [`defaults.json`](../../../../../packages/cheatsheet/src/lib/sampleSpokenFormInfos/defaults.json). First make sure you have the `cursorless-talon-dev` user file set in your Talon home directory, as indicated in the [initial contributor setup instructions](CONTRIBUTING.mdx#initial-setup). Then you can say `"cursorless update cheatsheet"` to update the default spoken forms. Note that this will use your custom spoken forms, so you may need to do some manual cleanup.
 
 ## Running the cheatsheet in development mode
 

packages/cursorless-org-docs/src/docs/contributing/cursorless-in-neovim.md

@@ -8,7 +8,7 @@ Note that Cursorless is maintained as a monorepo, hosted at [`cursorless`](https
 
 ### 1. Follow the initial contributor setup guide
 
-Follow the steps in [CONTRIBUTING.md](./CONTRIBUTING.md#initial-setup).
+Follow the steps in [CONTRIBUTING.mdx](./CONTRIBUTING.mdx#initial-setup).
 
 ### 2. Get production Cursorless neovim working
 
@@ -45,7 +45,7 @@ In order to test out your local version of the extension or to run unit tests lo
 
 NOTE: This will spawn a standalone nvim instance that is independent of VSCode. Consequently after you're done debugging, you need to close nvim.
 
-If you don't have the `cursorless-talon-dev` files in your Talon user directory as described in step 6 of [CONTRIBUTING.md](./CONTRIBUTING.md#initial-setup), then you instead need to run the `workbench.action.debug.selectandstart` command in VSCode and then select either "Neovim: Run" or "Neovim: Test".
+If you don't have the `cursorless-talon-dev` files in your Talon user directory as described in step 6 of [CONTRIBUTING.mdx](./CONTRIBUTING.mdx#initial-setup), then you instead need to run the `workbench.action.debug.selectandstart` command in VSCode and then select either "Neovim: Run" or "Neovim: Test".
 
 ### Running lua tests
 

packages/cursorless-vscode/src/scripts/initLaunchSandbox.ts

@@ -6,23 +6,48 @@
 import { extensionDependencies } from "@cursorless/common";
 import * as cp from "child_process";
 
-const extraExtensions = ["pokey.command-server"];
+const vsCodeToolName: string = "code";
+const validCliToolParams: Array<string> = ["--code", "--codium"];
 
 async function main() {
   try {
+    // Read cli tool name from arguments, assume tool name is 'code' if not present
+    let cliToolName = vsCodeToolName;
+
+    process.argv.forEach((argument) => {
+      if (validCliToolParams.includes(argument)) {
+        cliToolName = argument.replace("--", "");
+        console.log("Cli tool name manually set to " + cliToolName);
+      }
+    });
+
+    const extensions = [...extensionDependencies, "pokey.command-server"];
+
+    // Do not attempt to install jrieken:vscode-tree-sitter-query if editor is NOT VSCode, assuming lack of access to VSCode Marketplace
+    if (cliToolName !== vsCodeToolName) {
+      extensions.splice(
+        extensions.findIndex((e) => e === "jrieken.vscode-tree-sitter-query"),
+        1,
+      );
+      console.log(
+        "Not installing jrieken:vscode-tree-sitter-query as it is not on the OpenVSX Marketplace.",
+      );
+      console.log(
+        "You should install this extension manually. Check the Cursorless contributor documentation for more info.",
+      );
+    }
+
     const args = [
       "--profile=cursorlessDevelopment",
-      ...[...extensionDependencies, ...extraExtensions].flatMap(
-        (dependency) => ["--install-extension", dependency],
-      ),
+      ...extensions.flatMap((e) => ["--install-extension", e]),
     ];
 
     if (process.argv.includes("--force")) {
       args.push("--force");
     }
 
     // Install extension dependencies
-    const subprocess = cp.spawn("code", args, {
+    const subprocess = cp.spawn(cliToolName, args, {
       stdio: "inherit",
       shell: true,
     });