chore: tag version v0.0.1

Author: zackiles

.github/workflows/release.yml

@@ -16,9 +16,9 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Deno
-        uses: denoland/setup-deno@v1
+        uses: denoland/setup-deno@v2
         with:
-          deno-version: v1.x
+          deno-version: v2.x
 
       - name: Cache Deno dependencies
         uses: actions/cache@v3

docs/prompt-context/building-a-release-pipeline.md

@@ -1,26 +1,26 @@
 # Automating Release Pipelines for Node, Deno, and Bun Projects
 
-Successfully automating releases for diverse Javascript and Typescript projects requires a unified yet flexible approach. We need to **detect each project’s runtime and type**, then run the appropriate build and publish steps. Below, we outline how to identify the project type from config files, update configurations if needed, and implement a **GitHub Actions** workflow with accompanying scripts to handle library publishing, CLI distribution, and compiled binary releases for **Node.js**, **Deno**, and **Bun**.
+Successfully automating releases for diverse Javascript and Typescript projects requires a unified yet flexible approach. We need to **detect each project's runtime and type**, then run the appropriate build and publish steps. Below, we outline how to identify the project type from config files, update configurations if needed, and implement a **GitHub Actions** workflow with accompanying scripts to handle library publishing, CLI distribution, and compiled binary releases for **Node.js**, **Deno**, and **Bun**.
 
 ## 1. Detecting Runtime and Release Type
 
 Each project contains manifest files that signal its runtime and intended usage:
 
-* **Node.js projects**: Indicated by a `package.json`. We further check if it’s a CLI tool by looking for a `"bin"` field mapping command names to script files (e.g. `"bin": {"mytool": "src/cli.js"}`). Presence of `"bin"` means the package is a CLI tool (executables on install); absence suggests a library module.
+* **Node.js projects**: Indicated by a `package.json`. We further check if it's a CLI tool by looking for a `"bin"` field mapping command names to script files (e.g. `"bin": {"mytool": "src/cli.js"}`). Presence of `"bin"` means the package is a CLI tool (executables on install); absence suggests a library module.
 * **Bun projects**: Usually have a `bun.json`/`bunfig.toml` (in addition to or instead of `package.json`). Bun is largely Node-compatible, but a `bun.json` hints the project is optimized for Bun. If Bun config defines an executable entry (or the Node `"bin"` field is present), treat it as a CLI; otherwise a library.
-* **Deno projects**: Identified by a `deno.json`/`deno.jsonc`. Deno packages must have a `name`, `version`, and `exports` in this file for publishing. Deno doesn’t use a separate `"bin"` field; a Deno CLI vs library is determined by intent:
+* **Deno projects**: Identified by a `deno.json`/`deno.jsonc`. Deno packages must have a `name`, `version`, and `exports` in this file for publishing. Deno doesn't use a separate `"bin"` field; a Deno CLI vs library is determined by intent:
 
-  * If the code’s primary use is to be run (e.g. has a `main.ts` or similar that parses arguments or is referenced in documentation as a command), treat as a CLI tool.
-  * Otherwise, if it’s meant to be imported (e.g. provides functions/types), treat as a library.
-* **Compiled Binary**: Some CLI projects also require a **compiled binary** release (single-file executables) for convenience (no runtime needed). By default, we will produce binaries for CLI tools in Node and Bun (to run without Node/Bun installed), and optionally for Deno CLIs if needed for users without Deno. If it’s ambiguous (e.g. a Deno CLI might be fine with just `deno install`), we’d confirm with maintainers whether to provide a binary.
+  * If the code's primary use is to be run (e.g. has a `main.ts` or similar that parses arguments or is referenced in documentation as a command), treat as a CLI tool.
+  * Otherwise, if it's meant to be imported (e.g. provides functions/types), treat as a library.
+* **Compiled Binary**: Some CLI projects also require a **compiled binary** release (single-file executables) for convenience (no runtime needed). By default, we will produce binaries for CLI tools in Node and Bun (to run without Node/Bun installed), and optionally for Deno CLIs if needed for users without Deno. If it's ambiguous (e.g. a Deno CLI might be fine with just `deno install`), we'd confirm with maintainers whether to provide a binary.
 
 **Note:** If multiple configs exist (e.g. both `package.json` and `deno.json`), the project may target both Node (NPM) and Deno (JSR). In such cases, we can publish to both registries. If the intended release registry is unclear, we should ask the user to specify their preference (NPM vs JSR, or both).
 
 ## 2. Configuration Updates for Release Readiness
 
-Before writing the pipeline, ensure each project’s config is set up for smooth publishing:
+Before writing the pipeline, ensure each project's config is set up for smooth publishing:
 
-* **Node (and Bun) packages**: The `package.json` should have correct `name` (unique in npm), `version` (matching the tag to be released), and if it’s a library, an appropriate `"main"` or `"exports"` field for module entry. For TypeScript, include `"types"` pointing to the type definitions. If it’s a CLI, add a `"bin"` field mapping the command name to the compiled output or entry script. Also, set `"files"` or `.npmignore` to include built artifacts (and exclude source if not needed) so that `npm publish` packages the right files. For example, a Node CLI might have:
+* **Node (and Bun) packages**: The `package.json` should have correct `name` (unique in npm), `version` (matching the tag to be released), and if it's a library, an appropriate `"main"` or `"exports"` field for module entry. For TypeScript, include `"types"` pointing to the type definitions. If it's a CLI, add a `"bin"` field mapping the command name to the compiled output or entry script. Also, set `"files"` or `.npmignore` to include built artifacts (and exclude source if not needed) so that `npm publish` packages the right files. For example, a Node CLI might have:
 
   ```json
   {
@@ -46,7 +46,7 @@ Before writing the pipeline, ensure each project’s config is set up for smooth
 
   (The `"entry"` above is not official; the important field is `"exports"` for JSR).
 
-* **Bun projects**: Bun uses `package.json` for publishing (via `bun publish` to NPM), so ensure that’s updated. If a `bunfig.toml` or `bun.json` exists, verify it doesn’t conflict with package.json for name/version. For binaries, Bun will automatically append “.exe” on Windows builds, so our naming conventions should account for that.
+* **Bun projects**: Bun uses `package.json` for publishing (via `bun publish` to NPM), so ensure that's updated. If a `bunfig.toml` or `bun.json` exists, verify it doesn't conflict with package.json for name/version. For binaries, Bun will automatically append ".exe" on Windows builds, so our naming conventions should account for that.
 
 With configs in place, we can proceed to automation.
 
@@ -55,31 +55,31 @@ With configs in place, we can proceed to automation.
 We create a single workflow `.github/workflows/release.yml` that triggers on pushing a version tag. It will detect the project type and run the appropriate jobs:
 
 * **Trigger**: Only on new tags that look like version (e.g. `v*`) pushed to the main or master branch.
-* **Environment Matrix**: We may use a job matrix for building binaries on multiple OS, or use cross-compilation tools. Here we’ll demonstrate cross-compiling where possible to keep a single job, but note that Node’s official SEA feature might require per-OS jobs. We’ll use **Vercel pkg** for Node to allow cross-builds from one job, since Node’s Single Executable Application is experimental and multi-step.
+* **Environment Matrix**: We may use a job matrix for building binaries on multiple OS, or use cross-compilation tools. Here we'll demonstrate cross-compiling where possible to keep a single job, but note that Node's official SEA feature might require per-OS jobs. We'll use **Vercel pkg** for Node to allow cross-builds from one job, since Node's Single Executable Application is experimental and multi-step.
 * **Steps**:
 
   1. **Checkout code**.
   2. **Set up languages** (Node, Deno, or Bun) depending on project:
 
      * For Node: use `actions/setup-node@v3` to install appropriate Node version (and prepare npm auth).
      * For Bun: use `oven-sh/setup-bun@v2`.
-     * For Deno: use `denoland/setup-deno@v1` to get Deno on runner.
+     * For Deno: use `denoland/setup-deno@v2` to get Deno on runner.
   3. **Install Dependencies & Build**:
 
      * If Node or Bun and TypeScript, run `npm ci`/`bun install`, then a build script (e.g. `npm run build`) to produce JS in `dist/`.
      * If Deno, installation is not needed (Deno fetches deps on the fly), but we might run `deno check` or tests.
   4. **Publish to Registry** (if library or CLI package):
 
-     * For Node/Bun: use `npm publish` (or `bun publish`). We configure `NPM_TOKEN` for auth. (Bun’s publish packs and pushes to npm just like npm publish).
-     * For Deno: run `deno publish --token=${{ secrets.JSR_TOKEN }}` to publish to JSR (assuming we’ve created the package on JSR beforehand).
+     * For Node/Bun: use `npm publish` (or `bun publish`). We configure `NPM_TOKEN` for auth. (Bun's publish packs and pushes to npm just like npm publish).
+     * For Deno: run `deno publish --token=${{ secrets.JSR_TOKEN }}` to publish to JSR (assuming we've created the package on JSR beforehand).
   5. **Compile Binaries** (if CLI needs standalone binaries):
 
-     * **Node CLI**: Use `npx pkg` to compile for Linux, Windows, macOS in one go. For example, `pkg -t node18-linux-x64,node18-win-x64,node18-macos-x64 .` will output executables for each target. (We choose a Node runtime target matching our project’s requirements, e.g., Node 18 or `latest` for latest LTS).
+     * **Node CLI**: Use `npx pkg` to compile for Linux, Windows, macOS in one go. For example, `pkg -t node18-linux-x64,node18-win-x64,node18-macos-x64 .` will output executables for each target. (We choose a Node runtime target matching our project's requirements, e.g., Node 18 or `latest` for latest LTS).
      * **Deno CLI**: Use `deno compile`. We can cross-compile for all supported targets with `--target` flag (e.g., `deno compile -A --output mytool-linux --target x86_64-unknown-linux-gnu main.ts` and similarly for `*-windows-msvc` and `*-apple-darwin`). Deno will download the appropriate `denort` runtime for each target automatically.
      * **Bun CLI**: Use `bun build --compile` with `--target` for each platform. For example: `bun build --compile src/cli.ts --target=bun-linux-x64 --outfile mytool-linux` (and likewise `bun-windows-x64`, `bun-darwin-x64`, etc.). Bun supports cross-compiling via the `--target` option.
   6. **Prepare Release Assets**:
 
-     * Rename the binaries with a clear convention: e.g. `mytool-linux`, `mytool-macos`, `mytool-windows.exe` (include `.exe` for Windows) for clarity. We might archive them (e.g. zip/tar) or attach raw; to keep it simple we’ll attach raw binaries and ensure the install script accounts for platform naming.
+     * Rename the binaries with a clear convention: e.g. `mytool-linux`, `mytool-macos`, `mytool-windows.exe` (include `.exe` for Windows) for clarity. We might archive them (e.g. zip/tar) or attach raw; to keep it simple we'll attach raw binaries and ensure the install script accounts for platform naming.
      * Generate or update the **`install.sh`** script in the repository root. This script will let users install the latest release easily: it will detect OS and arch, fetch the appropriate binary from GitHub Releases, install it to `/usr/local/bin` (or another prefix), and print usage instructions. We write this script once (committed to the repo) and it always pulls the **latest** release by default. Optionally, allow specifying a version: if user passes an argument (version tag), the script uses that instead of latest.
   7. **Create GitHub Release**:
 
@@ -114,7 +114,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       NODE_VERSION: "18"        # Node version for Node/Bun projects
-      DENO_VERSION: "1.x"       # Deno version (if needed specific)
+      DENO_VERSION: "2.x"       # Deno version (if needed specific)
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -181,7 +181,7 @@ jobs:
 
       - name: Setup Deno (if Deno)
         if: env.RUNTIME == 'deno'
-        uses: denoland/setup-deno@v1
+        uses: denoland/setup-deno@v2
         with:
           deno-version: ${{ env.DENO_VERSION }}
 
@@ -307,7 +307,7 @@ fi
 **Notes:**
 
 * For **npm** publishing, we use `npm publish`. The `actions/setup-node` step in the workflow already created an `.npmrc` with the token, so `npm publish` will succeed. We include `--access public` for scoped packages.
-* For **JSR (Deno)**, we use `deno publish`. If `JSR_TOKEN` is provided, we pass it (to avoid interactive login). Deno’s OIDC flow (tokenless from GitHub Actions using Sigstore) could be enabled by setting `permissions:id-token: write` and omitting the token, but using a token is straightforward.
+* For **JSR (Deno)**, we use `deno publish`. If `JSR_TOKEN` is provided, we pass it (to avoid interactive login). Deno's OIDC flow (tokenless from GitHub Actions using Sigstore) could be enabled by setting `permissions:id-token: write` and omitting the token, but using a token is straightforward.
 * For **Bun**, `bun publish` will pack and publish to the npm registry using the same credentials as npm (it respects `.npmrc` or environment).
 
 ### `bin/release.sh` – Building Binaries and Preparing Assets
@@ -411,14 +411,14 @@ fi
 A few points about `bin/release.sh`:
 
 * It finds a base `NAME` for the binaries, typically the package name without scope (e.g. `"@org/mytool"` -> `mytool`). This name will be used in the filenames.
-* **Node**: We install or use `pkg` to create binaries for all three platforms in one command. The script picks the entry point from package.json (`bin` or `main`). We rename outputs to a consistent scheme. (Using Node’s official SEA would involve a more complex process including `--experimental-sea-config` and `postject` injection – for simplicity and automation, we use `pkg` here.)
+* **Node**: We install or use `pkg` to create binaries for all three platforms in one command. The script picks the entry point from package.json (`bin` or `main`). We rename outputs to a consistent scheme. (Using Node's official SEA would involve a more complex process including `--experimental-sea-config` and `postject` injection – for simplicity and automation, we use `pkg` here.)
 * **Deno**: We compile 4 binaries: linux x64, macOS x64, macOS arm64, and Windows x64. This covers common platforms. (We could also build Linux arm64 if needed by adding `aarch64-unknown-linux-gnu`.)
-* **Bun**: We compile for Linux x64, Windows x64, and macOS x64. (Bun can also produce macOS arm64 if run on an ARM host or in cross-mode, but here we assume x64 build. We note that Bun’s `--target` has baseline vs modern variants; using default ensures broad compatibility.)
-* The script creates an `install.sh` if one doesn’t exist. In practice, you’d create this script once manually with the correct `REPO` placeholder. We show it being generated for completeness. The script:
+* **Bun**: We compile for Linux x64, Windows x64, and macOS x64. (Bun can also produce macOS arm64 if run on an ARM host or in cross-mode, but here we assume x64 build. We note that Bun's `--target` has baseline vs modern variants; using default ensures broad compatibility.)
+* The script creates an `install.sh` if one doesn't exist. In practice, you'd create this script once manually with the correct `REPO` placeholder. We show it being generated for completeness. The script:
 
-  * Fetches the latest release tag via GitHub’s API (unless a version argument is given).
+  * Fetches the latest release tag via GitHub's API (unless a version argument is given).
   * Detects OS and sets the expected asset name (this simple version lumps all Linux under one and all macOS under one, assuming x64 works on ARM via Rosetta – one could refine to pick an ARM binary if available).
-  * Downloads the asset and installs it to `/usr/local/bin` (using `~/.local/bin` if the former isn’t accessible).
+  * Downloads the asset and installs it to `/usr/local/bin` (using `~/.local/bin` if the former isn't accessible).
   * Makes the binary executable and prints a success message.
   * For Windows, since this is a Bash script, it would typically be run in WSL or Git Bash. Windows users not using a UNIX shell can manually download the `.exe` or use a PowerShell equivalent script (not included here).
 
@@ -433,7 +433,7 @@ This will install the latest version of **mytool** on their system.
 
 ## 4. Summary of Benefits and Maintenance
 
-By following this template, each project’s CI/CD pipeline will automatically:
+By following this template, each project's CI/CD pipeline will automatically:
 
 * **Detect the runtime and project type** (Node library, Node CLI, Deno lib/CLI, Bun project, etc.) and run the correct build and release steps.
 * **Publish libraries** to the appropriate registry:
@@ -445,8 +445,8 @@ By following this template, each project’s CI/CD pipeline will automatically:
   * **npm/JSR** for package installation (e.g. `npm -g` or `deno add`), and/or
   * **GitHub Releases** with pre-built binaries for macOS, Linux, and Windows, plus an easy installer script (`curl | sh`).
 * **Trigger on tagged releases** ensuring that new versions are released only when you push a version tag (e.g. `v1.2.3`) to the main branch, aligning with Git flow.
-* **Isolate build logic** in version-controlled scripts (`/bin`) and configuration in `.github/workflows`, making it easy to update across many projects. There’s no magic – just standard tools as documented by Node, Deno, and Bun.
-* **Support all platforms**: We produced platform-specific binaries using each runtime’s official capability (Node’s packagers, Deno’s native compiler, Bun’s compiler) so users on Windows, Linux, or macOS are all covered. For example, Deno’s compiler can target all supported OSes from a single machine, and Bun’s `--target` can cross-compile executables as well. Node’s `pkg` can bundle for multiple platforms in one go.
-* **Minimal intervention**: once this is set up, maintainers only need to update version numbers and push tags. The workflow and scripts handle the rest automatically. If a project’s intent is unclear (e.g. a Deno project that could be both a library and an app), the detection logic can be refined or a one-time manual tweak can be made to the script for that repository.
+* **Isolate build logic** in version-controlled scripts (`/bin`) and configuration in `.github/workflows`, making it easy to update across many projects. There's no magic – just standard tools as documented by Node, Deno, and Bun.
+* **Support all platforms**: We produced platform-specific binaries using each runtime's official capability (Node's packagers, Deno's native compiler, Bun's compiler) so users on Windows, Linux, or macOS are all covered. For example, Deno's compiler can target all supported OSes from a single machine, and Bun's `--target` can cross-compile executables as well. Node's `pkg` can bundle for multiple platforms in one go.
+* **Minimal intervention**: once this is set up, maintainers only need to update version numbers and push tags. The workflow and scripts handle the rest automatically. If a project's intent is unclear (e.g. a Deno project that could be both a library and an app), the detection logic can be refined or a one-time manual tweak can be made to the script for that repository.
 
 By leveraging official tools and documentation from each ecosystem – Node (npm, pkg, or SEA), Deno (JSR and `deno compile`), and Bun (bun build/publish) – this solution provides a **consistent release process** across all projects. It ensures that libraries reach the right package registries and that CLI applications are easily installable in any environment, all through automated GitHub Actions workflows.