chore(release): v0.0.8

Reviewed-on: #3

.github/workflows/BUILD.bazel

@@ -1,3 +1,6 @@
 package(default_visibility = ["//visibility:public"])
 
-exports_files(["ci.yml"])
+exports_files([
+    "ci.yml",
+    "pages.yml",
+])

.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Docs Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      USE_BAZEL_VERSION: 9.0.0
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: bazel-contrib/setup-bazel@0.15.0
+
+      - name: Generate rule docs
+        run: |
+          bazel build //docs:rules_md
+          cp bazel-bin/docs/rules.md docs/rules.md
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: docs
+          destination: _site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

MODULE.bazel

@@ -1,18 +1,20 @@
 module(
     name = "rules_bun",
-    version = "0.1.0",
+    version = "0.0.8",
 )
 
 bazel_dep(name = "platforms", version = "1.0.0")
 bazel_dep(name = "rules_shell", version = "0.6.1")
+bazel_dep(name = "bazel_skylib", version = "1.8.2")
+bazel_dep(name = "stardoc", version = "0.7.2")
 
 bun_ext = use_extension("//bun:extensions.bzl", "bun")
 use_repo(
     bun_ext,
-    "bun_linux_x64",
-    "bun_linux_aarch64",
-    "bun_darwin_x64",
     "bun_darwin_aarch64",
+    "bun_darwin_x64",
+    "bun_linux_aarch64",
+    "bun_linux_x64",
     "bun_windows_x64",
 )
 

MODULE.bazel.lock

@@ -189,8 +189,8 @@
   "moduleExtensions": {
     "//bun:extensions.bzl%bun": {
       "general": {
-        "bzlTransitiveDigest": "Q0uQOwFAgAU+etePCZ4TUDO+adLX7Z0EmRLaEsKgncw=",
+        "bzlTransitiveDigest": "oLR98WtKDCc+zh7Tvu9jtakNg8q/T1IPE38QR1FEQtI=",
-        "usagesDigest": "qk1PDh3WICa0VONYKXJLsmWCesNJxz3Jkb/aH/voIeI=",
+        "usagesDigest": "NfJgMuTjZXXRLr1/kxxFkS1IKV2UyehFyr3fMvAke/k=",
         "recordedInputs": [
           "REPO_MAPPING:,bazel_tools bazel_tools"
         ],

README.md

@@ -2,52 +2,159 @@
 
 Bazel rules for bun.
 
-## Current status
+## Rule reference
 
-Phase 1 bootstrap is in place:
+- Published docs site: https://eriyc.github.io/rules_bun/
+- Generated API docs: [docs/rules.md](docs/rules.md)
+- Regenerate: `bazel build //docs:rules_md && cp bazel-bin/docs/rules.md docs/rules.md`
 
-- Bun toolchain rule and provider (`/bun/toolchain.bzl`)
+## Use
-- Platform-specific Bun repository downloads (`/bun/repositories.bzl`)
-- Toolchain declarations and registration targets (`/bun/BUILD.bazel`)
-- Smoke test for `bun --version` (`//tests/toolchain_test:bun_version_test`)
 
-Phase 2 bootstrap is in place:
+These steps show how to consume a tagged release of `rules_bun` in a separate Bazel workspace.
 
-- Repository-rule based `bun_install` (`/internal/bun_install.bzl`)
+### 1) Add the module dependency
-- Public export via `bun/defs.bzl`
-- Focused install behavior tests (`//tests/install_test:all`)
 
-Phase 3 bootstrap is in place:
+In your project's `MODULE.bazel`, add:
 
-- Executable `bun_binary` rule (`/internal/bun_binary.bzl`)
+```starlark
-- Public export via `bun/defs.bzl`
+bazel_dep(name = "rules_bun", version = "0.0.8")
-- Focused JS/TS runnable tests (`//tests/binary_test:all`)
 
-Phase 4 bootstrap is in place:
+archive_override(
+	module_name = "rules_bun",
+	urls = ["https://github.com/Eriyc/rules_bun/archiv0.0.5.tar.gz"],
+	strip_prefix = "rules_bun-v0.0.8",
+)
+```
 
-- Test rule `bun_test` (`/internal/bun_test.bzl`)
+For channel/pre-release tags (for example `v0.0.8-rc.1`), use the matching folder prefix:
-- Public export via `bun/defs.bzl`
-- Focused passing/failing test targets (`//tests/bun_test_test:all`)
 
-Phase 5 bootstrap is in place:
+```starlark
+bazel_dep(name = "rules_bun", version = "0.0.8-rc.1")
 
-- Bundle rule `bun_bundle` (`/internal/bun_bundle.bzl`)
+archive_override(
-- Public export via `bun/defs.bzl`
+	module_name = "rules_bun",
-- Focused output/minify tests (`//tests/bundle_test:all`)
+	urls = ["https://github.com/Eriyc/rules_bun/archiv0.0.5-rc.1.tar.gz"],
+	strip_prefix = "rules_bun-v0.0.8-rc.1",
+)
+```
 
-Phase 6 bootstrap is in place:
+Note: keep the `v` prefix in the Git tag URL and `strip_prefix`; for `bazel_dep(..., version = ...)`, use the module version string without the leading `v`.
 
-- Source grouping rules `js_library` / `ts_library` (`/internal/js_library.bzl`)
+### 2) Create Bun repositories with the extension
-- Transitive `deps` propagation wired into `bun_bundle` and `bun_test`
-- Focused dependency-propagation tests (`//tests/library_test:all`)
 
-Phase 7 bootstrap is in place:
+Still in `MODULE.bazel`, add:
 
-- Bzlmod `bun_install` module extension (`/bun/extensions.bzl`) using Bazel 9-compatible extension/tag syntax
+```starlark
-- Focused module-extension shape test (`//tests/install_extension_test:all`)
+bun_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun")
 
-Phase 8 bootstrap is in place:
+use_repo(
+	bun_ext,
+	"bun_linux_x64",
+	"bun_linux_aarch64",
+	"bun_darwin_x64",
+	"bun_darwin_aarch64",
+	"bun_windows_x64",
+)
+```
 
-- CI matrix workflow for linux-x64, darwin-arm64, and windows (`/.github/workflows/ci.yml`)
+### 3) Register toolchains
-- Bazel 9 pin in CI via `USE_BAZEL_VERSION=9.0.0`
+
-- Focused CI matrix shape test (`//tests/ci_test:all`)
+Also in `MODULE.bazel`, register:
+
+```starlark
+register_toolchains(
+	"@rules_bun//bun:darwin_aarch64_toolchain",
+	"@rules_bun//bun:darwin_x64_toolchain",
+	"@rules_bun//bun:linux_aarch64_toolchain",
+	"@rules_bun//bun:linux_x64_toolchain",
+	"@rules_bun//bun:windows_x64_toolchain",
+)
+```
+
+### 4) Load rules in `BUILD.bazel`
+
+```starlark
+load(
+	"@rules_bun//bun:defs.bzl",
+	"bun_binary",
+	"bun_bundle",
+	"bun_dev",
+	"bun_test",
+	"js_library",
+	"ts_library",
+)
+```
+
+### 5) (Optional) Use `bun_install` module extension
+
+If you want Bazel-managed install repositories, add:
+
+```starlark
+bun_install_ext = use_extension("@rules_bun//bun:extensions.bzl", "bun_install")
+
+bun_install_ext.install(
+	name = "npm",
+	package_json = "//:package.json",
+	bun_lockfile = "//:bun.lock",
+)
+
+use_repo(bun_install_ext, "npm")
+```
+
+### 6) Verify setup
+
+Run one of your bun-backed targets, for example:
+
+```bash
+bazel test //path/to:your_bun_test
+```
+
+All `rules_bun` rule-driven Bun invocations pass `--bun`.
+
+## Development mode (`bun_dev`)
+
+Use `bun_dev` for long-running local development with Bun watch mode.
+
+```starlark
+load("@rules_bun//bun:defs.bzl", "bun_dev")
+
+bun_dev(
+	name = "web_dev",
+	entry_point = "src/main.ts",
+	# Optional: run from the entry point directory so Bun auto-loads colocated .env files.
+	# working_dir = "entry_point",
+)
+```
+
+Run it with:
+
+```bash
+bazel run //path/to:web_dev
+```
+
+`bun_dev` supports:
+
+- `watch_mode = "watch"` (default) for `bun --watch`
+- `watch_mode = "hot"` for `bun --hot`
+- `restart_on = [...]` to force full process restarts when specific files change
+- `working_dir = "workspace" | "entry_point"` (default: `workspace`)
+
+## Runtime working directory (`bun_binary`, `bun_dev`)
+
+`bun_binary` and `bun_dev` support `working_dir`:
+
+- `"workspace"` (default): runs from the Bazel runfiles workspace root.
+- `"entry_point"`: runs from the nearest ancestor of the entry point that contains `.env` or `package.json` (falls back to the entry point directory).
+
+Use `"entry_point"` when Bun should resolve local files such as colocated `.env` files relative to the program directory.
+
+### Hybrid Go + Bun + protobuf workflow
+
+For monorepos that mix Go and Bun (including FFI):
+
+1. Run Bun app with native watch/HMR via `bun_dev`.
+2. Put generated artifacts or bridge files in `restart_on` (for example generated JS/TS files from proto/go steps).
+3. Rebuild Go/proto artifacts separately (for example with `ibazel build`) so their output files change.
+4. `bun_dev` detects those `restart_on` changes and restarts Bun, while ordinary JS edits continue to use Bun watch/HMR without full Bazel restarts.
+
+This keeps the fast Bun JS loop while still supporting full restarts when non-JS dependencies change.

VERSION

@@ -1,3 +1,3 @@
-0.0.2
+0.0.8
 stable
 0

bun/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load(":toolchain.bzl", "bun_toolchain")
 load(":version.bzl", "BUN_VERSION")
 
@@ -6,6 +7,26 @@ exports_files([
     "extensions.bzl",
 ])
 
+bzl_library(
+    name = "toolchain_bzl",
+    srcs = ["toolchain.bzl"],
+    visibility = ["//visibility:public"],
+)
+
+bzl_library(
+    name = "defs_bzl",
+    srcs = ["defs.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":toolchain_bzl",
+        "//internal:bun_binary_bzl",
+        "//internal:bun_bundle_bzl",
+        "//internal:bun_dev_bzl",
+        "//internal:bun_test_bzl",
+        "//internal:js_library_bzl",
+    ],
+)
+
 toolchain_type(name = "toolchain_type")
 
 bun_toolchain(

bun/defs.bzl

@@ -1,5 +1,7 @@
+"""Public API surface for Bun Bazel rules."""
 load("//internal:bun_binary.bzl", _bun_binary = "bun_binary")
 load("//internal:bun_bundle.bzl", _bun_bundle = "bun_bundle")
+load("//internal:bun_dev.bzl", _bun_dev = "bun_dev")
 load("//internal:bun_test.bzl", _bun_test = "bun_test")
 load("//internal:js_library.bzl", _js_library = "js_library", _ts_library = "ts_library")
 load(":toolchain.bzl", _BunToolchainInfo = "BunToolchainInfo", _bun_toolchain = "bun_toolchain")
@@ -8,8 +10,10 @@ visibility("public")
 
 bun_binary = _bun_binary
 bun_bundle = _bun_bundle
+bun_dev = _bun_dev
 bun_test = _bun_test
 js_library = _js_library
 ts_library = _ts_library
 BunToolchainInfo = _BunToolchainInfo
 bun_toolchain = _bun_toolchain
+ 

docs/BUILD.bazel

@@ -0,0 +1,18 @@
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+
+package(default_visibility = ["//visibility:public"])
+
+stardoc(
+    name = "rules_md",
+    out = "rules.md",
+    input = "//bun:defs.bzl",
+    symbol_names = [
+        "bun_binary",
+        "bun_bundle",
+        "bun_dev",
+        "bun_test",
+        "js_library",
+        "ts_library",
+    ],
+    deps = ["//bun:defs_bzl"],
+)

docs/index.md

@@ -0,0 +1,16 @@
+# rules_bun docs
+
+Documentation site for `rules_bun`.
+
+## Rule reference
+
+- [rules.md](rules.md)
+
+## Regeneration
+
+The rule reference is generated from Starlark rule docstrings:
+
+```bash
+bazel build //docs:rules_md
+cp bazel-bin/docs/rules.md docs/rules.md
+```

docs/rules.md

@@ -0,0 +1,72 @@
+# rules_bun rule reference
+
+This file documents the public rules exported from `@rules_bun//bun:defs.bzl`.
+
+## bun_binary
+
+Runs a JS/TS entry point with Bun as an executable target (`bazel run`).
+
+Attributes:
+
+- `entry_point` (label, required): path to the main JS/TS file to execute.
+- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `data` (label_list, optional): additional runtime files.
+- `working_dir` (string, default: `"workspace"`, values: `"workspace" | "entry_point"`): runtime working directory.
+
+## bun_dev
+
+Runs a JS/TS entry point in Bun development watch mode (`bazel run`).
+
+Attributes:
+
+- `entry_point` (label, required): path to the main JS/TS file.
+- `watch_mode` (string, default: `"watch"`, values: `"watch" | "hot"`): Bun live-reload mode.
+- `restart_on` (label_list, optional): files that trigger full process restart when changed.
+- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `data` (label_list, optional): additional runtime files for dev process.
+- `working_dir` (string, default: `"workspace"`, values: `"workspace" | "entry_point"`): runtime working directory.
+
+## bun_bundle
+
+Bundles one or more JS/TS entry points with Bun build.
+
+Attributes:
+
+- `entry_points` (label_list, required): entry files to bundle.
+- `node_modules` (label, optional): Bun/npm package files for resolution.
+- `deps` (label_list, optional): source/library dependencies for transitive inputs.
+- `data` (label_list, optional): additional non-source files needed during bundling.
+- `target` (string, default: `"browser"`, values: `"browser" | "node" | "bun"`): Bun build target.
+- `format` (string, default: `"esm"`, values: `"esm" | "cjs" | "iife"`): module format.
+- `minify` (bool, default: `False`): minifies bundle output.
+- `sourcemap` (bool, default: `False`): emits source maps.
+- `external` (string_list, optional): package names treated as external (not bundled).
+
+## bun_test
+
+Runs Bun tests as a Bazel test target (`bazel test`).
+
+Attributes:
+
+- `srcs` (label_list, required): test source files passed to `bun test`.
+- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `deps` (label_list, optional): library dependencies required by tests.
+- `data` (label_list, optional): additional runtime files needed by tests.
+
+## js_library
+
+Aggregates JavaScript sources and transitive Bun source dependencies.
+
+Attributes:
+
+- `srcs` (label_list, optional): `.js`, `.jsx`, `.mjs`, `.cjs` files.
+- `deps` (label_list, optional): dependent source libraries.
+
+## ts_library
+
+Aggregates TypeScript sources and transitive Bun source dependencies.
+
+Attributes:
+
+- `srcs` (label_list, optional): `.ts`, `.tsx` files.
+- `deps` (label_list, optional): dependent source libraries.

examples/basic/BUILD.bazel

@@ -1,5 +1,13 @@
+load("//bun:defs.bzl", "bun_dev")
+
 package(default_visibility = ["//visibility:public"])
 
 exports_files([
 	"README.md",
+	"main.ts",
 ])
+
+bun_dev(
+    name = "web_dev",
+    entry_point = "main.ts",
+)

examples/basic/README.md

@@ -1,3 +1,11 @@
 # basic example
 
-Placeholder for end-to-end bun rules example.
+Minimal `bun_dev` example.
+
+Run:
+
+```bash
+bazel run //examples/basic:web_dev
+```
+
+This starts Bun in watch mode for `main.ts`.

examples/basic/main.ts

@@ -0,0 +1 @@
+console.log("rules_bun bun_dev example");

examples/workspace/BUILD.bazel

@@ -0,0 +1,22 @@
+load("//bun:defs.bzl", "bun_bundle", "ts_library")
+
+package(default_visibility = ["//visibility:public"])
+
+exports_files([
+    "README.md",
+    "package.json",
+    "packages/pkg-a/package.json",
+    "packages/pkg-b/package.json",
+])
+
+ts_library(
+    name = "pkg_a_lib",
+    srcs = ["packages/pkg-a/index.ts"],
+)
+
+bun_bundle(
+    name = "pkg_b_bundle",
+    entry_points = ["packages/pkg-b/main.ts"],
+    deps = [":pkg_a_lib"],
+    target = "bun",
+)

examples/workspace/README.md

@@ -0,0 +1,14 @@
+# workspace example
+
+Minimal Bun workspace-style layout with two packages:
+
+- `@workspace/pkg-a`: exports a string helper
+- `@workspace/pkg-b`: imports from `pkg-a` and prints the message
+
+The workspace root also defines a Bun `catalog` pin for `lodash`, and both packages consume it via `"lodash": "catalog:"` to keep versions consistent across packages.
+
+This example demonstrates building a target from a workspace-shaped directory tree with Bazel:
+
+```bash
+bazel build //examples/workspace:pkg_b_bundle
+```

examples/workspace/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "workspace-root",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "catalog": {
+    "lodash": "^4.17.21"
+  }
+}

examples/workspace/packages/pkg-a/index.ts

@@ -0,0 +1,3 @@
+export function workspaceMessage(): string {
+  return "workspace-pkg-a";
+}

examples/workspace/packages/pkg-a/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@workspace/pkg-a",
+  "version": "1.0.0",
+  "main": "index.ts",
+  "dependencies": {
+    "lodash": "catalog:"
+  }
+}

examples/workspace/packages/pkg-b/main.ts

@@ -0,0 +1,3 @@
+import { workspaceMessage } from "../pkg-a/index";
+
+console.log(`hello-${workspaceMessage()}`);

examples/workspace/packages/pkg-b/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@workspace/pkg-b",
+  "version": "1.0.0",
+  "dependencies": {
+    "@workspace/pkg-a": "workspace:*",
+    "lodash": "catalog:"
+  }
+}

flake.nix

@@ -130,7 +130,43 @@
         release = devshell-lib.lib.mkRelease {
           inherit system;
 
-          release = [ ];
+          release = [
+            {
+              run = ''
+                sed -E -i 's#^([[:space:]]*version[[:space:]]*=[[:space:]]*")[^"]*(",)$#\1'"$FULL_VERSION"'\2#' "$ROOT_DIR/MODULE.bazel"
+              '';
+            }
+            {
+              run = ''
+                README="$ROOT_DIR/README.md"
+                TMP="$README.tmp"
+
+                awk -v stable="$BASE_VERSION" -v prerelease="$BASE_VERSION-rc.1" '
+                  {
+                    line = $0
+
+                    if (line ~ /bazel_dep\(name = "rules_bun", version = "/ && line !~ /-rc\.1/) {
+                      sub(/version = "[^"]+"/, "version = \"" stable "\"", line)
+                    } else if (line ~ /bazel_dep\(name = "rules_bun", version = "/ && line ~ /-rc\.1/) {
+                      sub(/version = "[^"]+"/, "version = \"" prerelease "\"", line)
+                    } else if (line ~ /archive\/refs\/tags\/v/ && line !~ /-rc\.1/) {
+                      sub(/v[^"]+\.tar\.gz/, "v" stable ".tar.gz", line)
+                    } else if (line ~ /archive\/refs\/tags\/v/ && line ~ /-rc\.1/) {
+                      sub(/v[^"]+\.tar\.gz/, "v" prerelease ".tar.gz", line)
+                    } else if (line ~ /strip_prefix = "rules_bun-v/ && line !~ /-rc\.1/) {
+                      sub(/rules_bun-v[^"]+/, "rules_bun-v" stable, line)
+                    } else if (line ~ /strip_prefix = "rules_bun-v/ && line ~ /-rc\.1/) {
+                      sub(/rules_bun-v[^"]+/, "rules_bun-v" prerelease, line)
+                    } else if (line ~ /For channel\/pre-release tags \(for example `v.*-rc\.1`\), use the matching folder prefix:/) {
+                      sub(/`v[^`]+`/, "`v" prerelease "`", line)
+                    }
+
+                    print line
+                  }
+                ' "$README" > "$TMP" && mv "$TMP" "$README"
+              '';
+            }
+          ];
 
           postVersion = ''
             echo "Released $FULL_TAG"

internal/BUILD.bazel

@@ -1,9 +1,39 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
 package(default_visibility = ["//visibility:public"])
 
 exports_files([
-	"bun_binary.bzl",
+    "bun_binary.bzl",
-	"bun_bundle.bzl",
+    "bun_bundle.bzl",
-	"bun_install.bzl",
+    "bun_dev.bzl",
-	"bun_test.bzl",
+    "bun_install.bzl",
-	"js_library.bzl",
+    "bun_test.bzl",
+    "js_library.bzl",
 ])
+
+bzl_library(
+    name = "bun_binary_bzl",
+    srcs = ["bun_binary.bzl"],
+)
+
+bzl_library(
+    name = "bun_bundle_bzl",
+    srcs = ["bun_bundle.bzl"],
+    deps = [":js_library_bzl"],
+)
+
+bzl_library(
+    name = "bun_dev_bzl",
+    srcs = ["bun_dev.bzl"],
+)
+
+bzl_library(
+    name = "bun_test_bzl",
+    srcs = ["bun_test.bzl"],
+    deps = [":js_library_bzl"],
+)
+
+bzl_library(
+    name = "js_library_bzl",
+    srcs = ["js_library.bzl"],
+)

internal/bun_binary.bzl

@@ -14,13 +14,38 @@ def _bun_binary_impl(ctx):
 set -euo pipefail
 
 runfiles_dir="${{RUNFILES_DIR:-$0.runfiles}}"
+workspace_root="${{runfiles_dir}}/_main"
 bun_bin="${{runfiles_dir}}/_main/{bun_short_path}"
 entry_point="${{runfiles_dir}}/_main/{entry_short_path}"
 
-exec "${{bun_bin}}" run "${{entry_point}}" "$@"
+resolve_entrypoint_workdir() {{
+    local dir
+    dir="$(dirname "${{entry_point}}")"
+    while [[ "${{dir}}" == "${{workspace_root}}"* ]]; do
+        if [[ -f "${{dir}}/.env" || -f "${{dir}}/package.json" ]]; then
+            echo "${{dir}}"
+            return 0
+        fi
+        if [[ "${{dir}}" == "${{workspace_root}}" ]]; then
+            break
+        fi
+        dir="$(dirname "${{dir}}")"
+    done
+    echo "$(dirname "${{entry_point}}")"
+}}
+
+working_dir="{working_dir}"
+if [[ "${{working_dir}}" == "entry_point" ]]; then
+    cd "$(resolve_entrypoint_workdir)"
+else
+    cd "${{workspace_root}}"
+fi
+
+exec "${{bun_bin}}" --bun run "${{entry_point}}" "$@"
 """.format(
             bun_short_path = bun_bin.short_path,
             entry_short_path = entry_point.short_path,
+            working_dir = ctx.attr.working_dir,
         ),
     )
 
@@ -43,13 +68,28 @@ exec "${{bun_bin}}" run "${{entry_point}}" "$@"
 
 bun_binary = rule(
     implementation = _bun_binary_impl,
+    doc = """Runs a JS/TS entry point with Bun as an executable target.
+
+Use this rule for non-test scripts and CLIs that should run via `bazel run`.
+""",
     attrs = {
         "entry_point": attr.label(
             mandatory = True,
             allow_single_file = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Path to the main JS/TS file to execute.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files in runfiles.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional runtime files required by the program.",
+        ),
+        "working_dir": attr.string(
+            default = "workspace",
+            values = ["workspace", "entry_point"],
+            doc = "Working directory at runtime: `workspace` root or nearest `entry_point` ancestor containing `.env`/`package.json`.",
         ),
-        "node_modules": attr.label(),
-        "data": attr.label_list(allow_files = True),
     },
     executable = True,
     toolchains = ["//bun:toolchain_type"],

internal/bun_bundle.bzl

@@ -27,6 +27,7 @@ def _bun_bundle_impl(ctx):
         outputs.append(output)
 
         args = ctx.actions.args()
+        args.add("--bun")
         args.add("build")
         args.add(entry.path)
         args.add("--outfile")
@@ -60,25 +61,47 @@ def _bun_bundle_impl(ctx):
 
 bun_bundle = rule(
     implementation = _bun_bundle_impl,
+    doc = """Bundles one or more JS/TS entry points using Bun build.
+
+Each entry point produces one output JavaScript artifact.
+""",
     attrs = {
         "entry_points": attr.label_list(
             mandatory = True,
             allow_files = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Entry files to bundle.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files for resolution.",
+        ),
+        "deps": attr.label_list(
+            doc = "Source/library dependencies that provide transitive inputs.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional non-source files needed during bundling.",
         ),
-        "node_modules": attr.label(),
-        "deps": attr.label_list(),
-        "data": attr.label_list(allow_files = True),
         "target": attr.string(
             default = "browser",
             values = ["browser", "node", "bun"],
+            doc = "Bun build target environment.",
         ),
         "format": attr.string(
             default = "esm",
             values = ["esm", "cjs", "iife"],
+            doc = "Output module format.",
+        ),
+        "minify": attr.bool(
+            default = False,
+            doc = "If true, minifies bundle output.",
+        ),
+        "sourcemap": attr.bool(
+            default = False,
+            doc = "If true, emits source maps.",
+        ),
+        "external": attr.string_list(
+            doc = "Package names to treat as externals (not bundled).",
         ),
-        "minify": attr.bool(default = False),
-        "sourcemap": attr.bool(default = False),
-        "external": attr.string_list(),
     },
     toolchains = ["//bun:toolchain_type"],
 )

internal/bun_dev.bzl

@@ -0,0 +1,186 @@
+"""Rule for running JS/TS scripts with Bun in watch mode for development."""
+
+def _bun_dev_impl(ctx):
+    toolchain = ctx.toolchains["//bun:toolchain_type"]
+    bun_bin = toolchain.bun.bun_bin
+    entry_point = ctx.file.entry_point
+
+    restart_watch_paths = "\n".join([path.short_path for path in ctx.files.restart_on])
+
+    launcher = ctx.actions.declare_file(ctx.label.name)
+    ctx.actions.write(
+        output = launcher,
+        is_executable = True,
+        content = """#!/usr/bin/env bash
+set -euo pipefail
+
+runfiles_dir="${{RUNFILES_DIR:-$0.runfiles}}"
+workspace_root="${{runfiles_dir}}/_main"
+bun_bin="${{runfiles_dir}}/_main/{bun_short_path}"
+entry_point="${{runfiles_dir}}/_main/{entry_short_path}"
+
+resolve_entrypoint_workdir() {{
+    local dir
+    dir="$(dirname "${{entry_point}}")"
+    while [[ "${{dir}}" == "${{workspace_root}}"* ]]; do
+        if [[ -f "${{dir}}/.env" || -f "${{dir}}/package.json" ]]; then
+            echo "${{dir}}"
+            return 0
+        fi
+        if [[ "${{dir}}" == "${{workspace_root}}" ]]; then
+            break
+        fi
+        dir="$(dirname "${{dir}}")"
+    done
+    echo "$(dirname "${{entry_point}}")"
+}}
+
+working_dir="{working_dir}"
+if [[ "${{working_dir}}" == "entry_point" ]]; then
+    cd "$(resolve_entrypoint_workdir)"
+else
+    cd "${{workspace_root}}"
+fi
+
+watch_mode="{watch_mode}"
+if [[ "${{watch_mode}}" == "hot" ]]; then
+    dev_flag="--hot"
+else
+    dev_flag="--watch"
+fi
+
+run_dev() {{
+    exec "${{bun_bin}}" --bun "${{dev_flag}}" run "${{entry_point}}" "$@"
+}}
+
+if [[ {restart_count} -eq 0 ]]; then
+    run_dev "$@"
+fi
+
+readarray -t restart_paths <<'EOF_RESTART_PATHS'
+{restart_watch_paths}
+EOF_RESTART_PATHS
+
+file_mtime() {{
+    local p="$1"
+    if stat -f '%m' "${{p}}" >/dev/null 2>&1; then
+        stat -f '%m' "${{p}}"
+        return 0
+    fi
+    stat -c '%Y' "${{p}}"
+}}
+
+declare -A mtimes
+for rel in "${{restart_paths[@]}}"; do
+    path="${{runfiles_dir}}/_main/${{rel}}"
+    if [[ -e "${{path}}" ]]; then
+        mtimes["${{rel}}"]="$(file_mtime "${{path}}")"
+    else
+        mtimes["${{rel}}"]="missing"
+    fi
+done
+
+child_pid=""
+restart_child() {{
+    if [[ -n "${{child_pid}}" ]] && kill -0 "${{child_pid}}" 2>/dev/null; then
+        kill "${{child_pid}}"
+        wait "${{child_pid}}" || true
+    fi
+    "${{bun_bin}}" --bun "${{dev_flag}}" run "${{entry_point}}" "$@" &
+    child_pid=$!
+}}
+
+cleanup() {{
+    if [[ -n "${{child_pid}}" ]] && kill -0 "${{child_pid}}" 2>/dev/null; then
+        kill "${{child_pid}}"
+        wait "${{child_pid}}" || true
+    fi
+}}
+
+trap cleanup EXIT INT TERM
+
+restart_child "$@"
+
+while true; do
+    sleep 1
+    changed=0
+    for rel in "${{restart_paths[@]}}"; do
+        path="${{runfiles_dir}}/_main/${{rel}}"
+        if [[ -e "${{path}}" ]]; then
+            current="$(file_mtime "${{path}}")"
+        else
+            current="missing"
+        fi
+        if [[ "${{current}}" != "${{mtimes[${{rel}}]}}" ]]; then
+            mtimes["${{rel}}"]="${{current}}"
+            changed=1
+        fi
+    done
+    if [[ "${{changed}}" -eq 1 ]]; then
+        restart_child "$@"
+    fi
+done
+""".format(
+            bun_short_path = bun_bin.short_path,
+            entry_short_path = entry_point.short_path,
+            watch_mode = ctx.attr.watch_mode,
+            working_dir = ctx.attr.working_dir,
+            restart_count = len(ctx.files.restart_on),
+            restart_watch_paths = restart_watch_paths,
+        ),
+    )
+
+    transitive_files = []
+    if ctx.attr.node_modules:
+        transitive_files.append(ctx.attr.node_modules[DefaultInfo].files)
+
+    runfiles = ctx.runfiles(
+        files = [bun_bin, entry_point] + ctx.files.data + ctx.files.restart_on,
+        transitive_files = depset(transitive = transitive_files),
+    )
+
+    return [
+        DefaultInfo(
+            executable = launcher,
+            runfiles = runfiles,
+        ),
+    ]
+
+bun_dev = rule(
+    implementation = _bun_dev_impl,
+    doc = """Runs a JS/TS entry point in Bun development watch mode.
+
+This rule is intended for local dev loops (`bazel run`) and supports Bun
+watch/HMR plus optional full restarts on selected file changes.
+""",
+    attrs = {
+        "entry_point": attr.label(
+            mandatory = True,
+            allow_single_file = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Path to the main JS/TS file to execute in dev mode.",
+        ),
+        "watch_mode": attr.string(
+            default = "watch",
+            values = ["watch", "hot"],
+            doc = "Bun live-reload mode: `watch` (default) or `hot`.",
+        ),
+        "restart_on": attr.label_list(
+            allow_files = True,
+            doc = "Files that trigger a full Bun process restart when they change.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files in runfiles.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional runtime files required by the dev process.",
+        ),
+        "working_dir": attr.string(
+            default = "workspace",
+            values = ["workspace", "entry_point"],
+            doc = "Working directory at runtime: `workspace` root or nearest `entry_point` ancestor containing `.env`/`package.json`.",
+        ),
+    },
+    executable = True,
+    toolchains = ["//bun:toolchain_type"],
+)

internal/bun_install.bzl

@@ -36,14 +36,14 @@ def _bun_install_repository_impl(repository_ctx):
     repository_ctx.symlink(bun_lockfile, "bun.lockb")
 
     result = repository_ctx.execute(
-        [str(bun_bin), "install", "--frozen-lockfile", "--no-progress"],
+        [str(bun_bin), "--bun", "install", "--frozen-lockfile", "--no-progress"],
         timeout = 600,
         quiet = False,
         environment = {"HOME": str(repository_ctx.path("."))},
     )
 
     if result.return_code:
-        fail("""bun_install failed running `bun install --frozen-lockfile`.
+        fail("""bun_install failed running `bun --bun install --frozen-lockfile`.
 stdout:
 {}
 stderr:

internal/bun_test.bzl

@@ -24,15 +24,15 @@ bun_bin="${{runfiles_dir}}/_main/{bun_short_path}"
 cd "${{runfiles_dir}}/_main"
 
 if [[ -n "${{TESTBRIDGE_TEST_ONLY:-}}" && -n "${{COVERAGE_DIR:-}}" ]]; then
-    exec "${{bun_bin}}" test {src_args} --test-name-pattern "${{TESTBRIDGE_TEST_ONLY}}" --coverage "$@"
+    exec "${{bun_bin}}" --bun test {src_args} --test-name-pattern "${{TESTBRIDGE_TEST_ONLY}}" --coverage "$@"
 fi
 if [[ -n "${{TESTBRIDGE_TEST_ONLY:-}}" ]]; then
-    exec "${{bun_bin}}" test {src_args} --test-name-pattern "${{TESTBRIDGE_TEST_ONLY}}" "$@"
+    exec "${{bun_bin}}" --bun test {src_args} --test-name-pattern "${{TESTBRIDGE_TEST_ONLY}}" "$@"
 fi
 if [[ -n "${{COVERAGE_DIR:-}}" ]]; then
-    exec "${{bun_bin}}" test {src_args} --coverage "$@"
+    exec "${{bun_bin}}" --bun test {src_args} --coverage "$@"
 fi
-exec "${{bun_bin}}" test {src_args} "$@"
+exec "${{bun_bin}}" --bun test {src_args} "$@"
 """.format(
                         bun_short_path = bun_bin.short_path,
             src_args = src_args,
@@ -63,14 +63,26 @@ exec "${{bun_bin}}" test {src_args} "$@"
 
 bun_test = rule(
     implementation = _bun_test_impl,
+    doc = """Runs Bun tests as a Bazel test target.
+
+Supports Bazel test filtering (`--test_filter`) and coverage integration.
+""",
     attrs = {
         "srcs": attr.label_list(
             mandatory = True,
             allow_files = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Test source files passed to `bun test`.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files in runfiles.",
+        ),
+        "deps": attr.label_list(
+            doc = "Library dependencies required by test sources.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional runtime files needed by tests.",
         ),
-        "node_modules": attr.label(),
-        "deps": attr.label_list(),
-        "data": attr.label_list(allow_files = True),
     },
     test = True,
     toolchains = ["//bun:toolchain_type"],

internal/js_library.bzl

@@ -21,20 +21,28 @@ def _bun_library_impl(ctx):
 
 js_library = rule(
     implementation = _bun_library_impl,
+    doc = "Aggregates JavaScript sources and transitive Bun source dependencies.",
     attrs = {
         "srcs": attr.label_list(
             allow_files = [".js", ".jsx", ".mjs", ".cjs"],
+            doc = "JavaScript source files in this library.",
+        ),
+        "deps": attr.label_list(
+            doc = "Other Bun source libraries to include transitively.",
         ),
-        "deps": attr.label_list(),
     },
 )
 
 ts_library = rule(
     implementation = _bun_library_impl,
+    doc = "Aggregates TypeScript sources and transitive Bun source dependencies.",
     attrs = {
         "srcs": attr.label_list(
             allow_files = [".ts", ".tsx"],
+            doc = "TypeScript source files in this library.",
+        ),
+        "deps": attr.label_list(
+            doc = "Other Bun source libraries to include transitively.",
         ),
-        "deps": attr.label_list(),
     },
 )

result

@@ -0,0 +1 @@
+/nix/store/742k6q4hns9h1wj61y90glqwfmn2y7pa-release

tests/binary_test/BUILD.bazel

@@ -43,3 +43,31 @@ sh_test(
         "//tests/binary_test:BUILD.bazel",
     ],
 )
+
+bun_binary(
+    name = "env_cwd_bin",
+    entry_point = "env.ts",
+    data = [".env"],
+    working_dir = "entry_point",
+)
+
+sh_test(
+    name = "bun_binary_env_cwd_test",
+    srcs = ["run_env_binary.sh"],
+    args = ["$(location :env_cwd_bin)"],
+    data = [":env_cwd_bin"],
+)
+
+bun_binary(
+    name = "env_parent_cwd_bin",
+    entry_point = "env_parent/src/main.ts",
+    data = ["env_parent/.env"],
+    working_dir = "entry_point",
+)
+
+sh_test(
+    name = "bun_binary_env_parent_cwd_test",
+    srcs = ["run_parent_env_binary.sh"],
+    args = ["$(location :env_parent_cwd_bin)"],
+    data = [":env_parent_cwd_bin"],
+)

tests/binary_test/env.ts

@@ -0,0 +1,2 @@
+const value = process.env.BUN_ENV_CWD_TEST ?? "missing";
+console.log(value);

tests/binary_test/env_parent/src/main.ts

@@ -0,0 +1,2 @@
+const value = process.env.BUN_ENV_PARENT_TEST ?? "missing";
+console.log(value);

tests/binary_test/run_env_binary.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+binary="$1"
+output="$(${binary})"
+
+if [[ ${output} != "from-dotenv" ]]; then
+  echo "Expected .env value from entry-point directory, got: ${output}" >&2
+  exit 1
+fi

tests/binary_test/run_parent_env_binary.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+binary="$1"
+output="$(${binary})"
+
+if [[ ${output} != "from-parent-dotenv" ]]; then
+  echo "Expected .env value from parent directory, got: ${output}" >&2
+  exit 1
+fi

tests/install_test/BUILD.bazel

@@ -76,3 +76,22 @@ sh_test(
     args = ["$(location //internal:bun_install.bzl)"],
     data = ["//internal:bun_install.bzl"],
 )
+
+sh_test(
+    name = "bun_install_workspaces_test",
+    srcs = ["workspaces.sh"],
+    args = select({
+        ":linux_x86_64": ["$(location @bun_linux_x64//:bun)"],
+        ":linux_aarch64": ["$(location @bun_linux_aarch64//:bun)"],
+        ":darwin_x86_64": ["$(location @bun_darwin_x64//:bun)"],
+        ":darwin_aarch64": ["$(location @bun_darwin_aarch64//:bun)"],
+        "//conditions:default": ["$(location @bun_linux_x64//:bun)"],
+    }),
+    data = select({
+        ":linux_x86_64": ["@bun_linux_x64//:bun"],
+        ":linux_aarch64": ["@bun_linux_aarch64//:bun"],
+        ":darwin_x86_64": ["@bun_darwin_x64//:bun"],
+        ":darwin_aarch64": ["@bun_darwin_aarch64//:bun"],
+        "//conditions:default": ["@bun_linux_x64//:bun"],
+    }),
+)

tests/install_test/workspaces.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bun_path="$1"
+workdir="$(mktemp -d)"
+trap 'rm -rf "${workdir}"' EXIT
+
+mkdir -p "${workdir}/packages/pkg-a" "${workdir}/packages/pkg-b"
+
+cat >"${workdir}/package.json" <<'JSON'
+{
+  "name": "workspace-root",
+  "private": true,
+  "workspaces": ["packages/*"]
+}
+JSON
+
+cat >"${workdir}/packages/pkg-a/package.json" <<'JSON'
+{
+  "name": "@workspace/pkg-a",
+  "version": "1.0.0",
+  "main": "index.js"
+}
+JSON
+
+cat >"${workdir}/packages/pkg-a/index.js" <<'JS'
+module.exports = { value: 42 };
+JS
+
+cat >"${workdir}/packages/pkg-b/package.json" <<'JSON'
+{
+  "name": "@workspace/pkg-b",
+  "version": "1.0.0",
+  "dependencies": {
+    "@workspace/pkg-a": "workspace:*"
+  },
+  "scripts": {
+    "check": "bun -e \"const { value } = require('@workspace/pkg-a'); if (value !== 42) process.exit(1)\""
+  }
+}
+JSON
+
+"${bun_path}" install --cwd "${workdir}" >/dev/null
+rm -rf "${workdir}/node_modules" "${workdir}/packages/pkg-b/node_modules"
+"${bun_path}" install --cwd "${workdir}" --frozen-lockfile >/dev/null
+"${bun_path}" run --cwd "${workdir}/packages/pkg-b" check >/dev/null

tests/integration_test/BUILD.bazel

@@ -13,6 +13,28 @@ sh_test(
     ],
 )
 
+sh_test(
+    name = "examples_workspace_bundle_e2e_test",
+    srcs = ["examples_workspace_bundle_e2e_test.sh"],
+    args = ["$(location //examples/workspace:pkg_b_bundle)"],
+    data = ["//examples/workspace:pkg_b_bundle"],
+)
+
+sh_test(
+    name = "examples_workspace_catalog_shape_test",
+    srcs = ["examples_workspace_catalog_shape_test.sh"],
+    args = [
+        "$(location //examples/workspace:package.json)",
+        "$(location //examples/workspace:packages/pkg-a/package.json)",
+        "$(location //examples/workspace:packages/pkg-b/package.json)",
+    ],
+    data = [
+        "//examples/workspace:package.json",
+        "//examples/workspace:packages/pkg-a/package.json",
+        "//examples/workspace:packages/pkg-b/package.json",
+    ],
+)
+
 sh_test(
     name = "repo_all_targets_test",
     srcs = ["repo_all_targets_test.sh"],

tests/integration_test/examples_workspace_bundle_e2e_test.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bundle_file="$1"
+
+[[ -f ${bundle_file} ]]
+grep -Eq 'hello-workspace-pkg-a|workspace-pkg-a' "${bundle_file}"

tests/integration_test/examples_workspace_catalog_shape_test.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_package_json="$1"
+pkg_a_package_json="$2"
+pkg_b_package_json="$3"
+
+grep -Eq '"catalog"[[:space:]]*:[[:space:]]*\{' "${root_package_json}"
+grep -Eq '"lodash"[[:space:]]*:[[:space:]]*"\^4\.17\.21"' "${root_package_json}"
+grep -Eq '"lodash"[[:space:]]*:[[:space:]]*"catalog:"' "${pkg_a_package_json}"
+grep -Eq '"lodash"[[:space:]]*:[[:space:]]*"catalog:"' "${pkg_b_package_json}"