docs: add plan to repo

Co-authored-by: Eriyc <50216491+Eriyc@users.noreply.github.com>

BUILD.bazel

@@ -0,0 +1 @@
+package(default_visibility = ["//visibility:public"])

MODULE.bazel

@@ -0,0 +1,6 @@
+module(
+    name = "rules_bun",
+    version = "0.1.0",
+)
+
+bazel_dep(name = "platforms", version = "1.0.0")

README.md

@@ -1,3 +1,12 @@
 # rules_bun
 
-Bazel rules for bun
+Bazel rules for bun.
+
+## Current status
+
+Phase 1 bootstrap is in place:
+
+- Bun toolchain rule and provider (`/bun/toolchain.bzl`)
+- 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`)

WORKSPACE

@@ -0,0 +1,5 @@
+workspace(name = "rules_bun")
+
+load("//bun:repositories.bzl", "bun_register_toolchains")
+
+bun_register_toolchains()

bun/BUILD.bazel

@@ -0,0 +1,104 @@
+load(":toolchain.bzl", "bun_toolchain")
+load(":version.bzl", "BUN_VERSION")
+
+toolchain_type(name = "toolchain_type")
+
+bun_toolchain(
+    name = "linux_x64_toolchain_impl",
+    bun = "@bun_linux_x64//:bun",
+    version = BUN_VERSION,
+)
+
+bun_toolchain(
+    name = "linux_aarch64_toolchain_impl",
+    bun = "@bun_linux_aarch64//:bun",
+    version = BUN_VERSION,
+)
+
+bun_toolchain(
+    name = "darwin_x64_toolchain_impl",
+    bun = "@bun_darwin_x64//:bun",
+    version = BUN_VERSION,
+)
+
+bun_toolchain(
+    name = "darwin_aarch64_toolchain_impl",
+    bun = "@bun_darwin_aarch64//:bun",
+    version = BUN_VERSION,
+)
+
+bun_toolchain(
+    name = "windows_x64_toolchain_impl",
+    bun = "@bun_windows_x64//:bun",
+    version = BUN_VERSION,
+)
+
+toolchain(
+    name = "linux_x64_toolchain",
+    exec_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:linux",
+    ],
+    target_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:linux",
+    ],
+    toolchain = ":linux_x64_toolchain_impl",
+    toolchain_type = ":toolchain_type",
+)
+
+toolchain(
+    name = "linux_aarch64_toolchain",
+    exec_compatible_with = [
+        "@platforms//cpu:arm64",
+        "@platforms//os:linux",
+    ],
+    target_compatible_with = [
+        "@platforms//cpu:arm64",
+        "@platforms//os:linux",
+    ],
+    toolchain = ":linux_aarch64_toolchain_impl",
+    toolchain_type = ":toolchain_type",
+)
+
+toolchain(
+    name = "darwin_x64_toolchain",
+    exec_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:macos",
+    ],
+    target_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:macos",
+    ],
+    toolchain = ":darwin_x64_toolchain_impl",
+    toolchain_type = ":toolchain_type",
+)
+
+toolchain(
+    name = "darwin_aarch64_toolchain",
+    exec_compatible_with = [
+        "@platforms//cpu:arm64",
+        "@platforms//os:macos",
+    ],
+    target_compatible_with = [
+        "@platforms//cpu:arm64",
+        "@platforms//os:macos",
+    ],
+    toolchain = ":darwin_aarch64_toolchain_impl",
+    toolchain_type = ":toolchain_type",
+)
+
+toolchain(
+    name = "windows_x64_toolchain",
+    exec_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:windows",
+    ],
+    target_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:windows",
+    ],
+    toolchain = ":windows_x64_toolchain_impl",
+    toolchain_type = ":toolchain_type",
+)

bun/defs.bzl

@@ -0,0 +1,9 @@
+load(":repositories.bzl", "bun_register_toolchains", "bun_repositories")
+load(":toolchain.bzl", "BunToolchainInfo", "bun_toolchain")
+
+__all__ = [
+    "BunToolchainInfo",
+    "bun_register_toolchains",
+    "bun_repositories",
+    "bun_toolchain",
+]

bun/repositories.bzl

@@ -0,0 +1,74 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load(":version.bzl", "BUN_VERSION")
+
+_BUN_ARCHIVES = {
+    "bun_linux_x64": {
+        "sha256": "a61da5357e28d4977fccd4851fed62ff4da3ea33853005c7dd93dac80bc53932",
+        "asset": "bun-linux-x64.zip",
+        "binary": "bun-linux-x64/bun",
+    },
+    "bun_linux_aarch64": {
+        "sha256": "3b08fd0b31f745509e1fed9c690c80d1a32ef2b3c8d059583f643f696639bd21",
+        "asset": "bun-linux-aarch64.zip",
+        "binary": "bun-linux-aarch64/bun",
+    },
+    "bun_darwin_x64": {
+        "sha256": "4e9814c9b2e64f9166ed8fc2a48f905a2195ea599b7ceda7ac821688520428a5",
+        "asset": "bun-darwin-x64.zip",
+        "binary": "bun-darwin-x64/bun",
+    },
+    "bun_darwin_aarch64": {
+        "sha256": "bbc6fb0e7bb99e7e95001ba05105cf09d0b79c06941d9f6ee3d0b34dc1541590",
+        "asset": "bun-darwin-aarch64.zip",
+        "binary": "bun-darwin-aarch64/bun",
+    },
+    "bun_windows_x64": {
+        "sha256": "52d6c588237c5a1071839dc20dc96f19ca9f8021b7757fa096d22927b0a44a8b",
+        "asset": "bun-windows-x64.zip",
+        "binary": "bun-windows-x64/bun.exe",
+    },
+}
+
+_BUN_GITHUB_RELEASE_URL_TEMPLATE = "https://github.com/oven-sh/bun/releases/download/bun-v{}/{}"
+
+
+def _declare_bun_repo(name, asset, sha256, binary, version):
+    if native.existing_rule(name):
+        return
+
+    http_archive(
+        name = name,
+        urls = [_BUN_GITHUB_RELEASE_URL_TEMPLATE.format(version, asset)],
+        sha256 = sha256,
+        build_file_content = """
+exports_files(["{binary}"])
+
+filegroup(
+    name = "bun",
+    srcs = ["{binary}"],
+    visibility = ["//visibility:public"],
+)
+""".format(binary = binary),
+    )
+
+
+def bun_repositories(version = BUN_VERSION):
+    for name, metadata in _BUN_ARCHIVES.items():
+        _declare_bun_repo(
+            name = name,
+            asset = metadata["asset"],
+            sha256 = metadata["sha256"],
+            binary = metadata["binary"],
+            version = version,
+        )
+
+
+def bun_register_toolchains(version = BUN_VERSION):
+    bun_repositories(version = version)
+    native.register_toolchains(
+        "//bun:darwin_aarch64_toolchain",
+        "//bun:darwin_x64_toolchain",
+        "//bun:linux_aarch64_toolchain",
+        "//bun:linux_x64_toolchain",
+        "//bun:windows_x64_toolchain",
+    )

bun/toolchain.bzl

@@ -0,0 +1,21 @@
+BunToolchainInfo = provider(fields = ["bun_bin", "version"])
+
+
+def _bun_toolchain_impl(ctx):
+    return [
+        platform_common.ToolchainInfo(
+            bun = BunToolchainInfo(
+                bun_bin = ctx.executable.bun,
+                version = ctx.attr.version,
+            ),
+        ),
+    ]
+
+
+bun_toolchain = rule(
+    implementation = _bun_toolchain_impl,
+    attrs = {
+        "bun": attr.label(allow_single_file = True, executable = True, cfg = "exec"),
+        "version": attr.string(mandatory = True),
+    },
+)

bun/version.bzl

@@ -0,0 +1 @@
+BUN_VERSION = "1.1.38"

examples/basic/BUILD.bazel

@@ -0,0 +1 @@
+package(default_visibility = ["//visibility:public"])

examples/basic/README.md

@@ -0,0 +1,3 @@
+# basic example
+
+Placeholder for end-to-end bun rules example.

implementation_plan.md

@@ -0,0 +1,242 @@
+Here's a comprehensive plan for implementing a Bazel-native `bun_rules` package:
+
+---
+
+## `bun_rules`: Bazel-Native Bun Implementation Plan
+
+### What Is This?
+
+A Bazel ruleset that integrates the [Bun](https://bun.sh) JavaScript runtime natively — similar to `rules_nodejs` but leveraging Bun's bundler, test runner, package manager, and runtime. The goal is hermetic, reproducible builds using Bun as the toolchain.
+
+---
+
+## Phase 1: Repository Skeleton & Toolchain
+
+**Where to start.** Every Bazel ruleset begins with the toolchain — nothing else works without it.
+
+### 1.1 Repo Structure
+```
+bun_rules/
+├── MODULE.bazel             # Bzlmod module definition
+├── WORKSPACE                # Legacy workspace support
+├── BUILD.bazel
+├── bun/
+│   ├── repositories.bzl     # Download bun binaries per platform
+│   ├── toolchain.bzl        # bun_toolchain rule
+│   └── defs.bzl             # Public API re-exports
+├── internal/
+│   ├── bun_binary.bzl
+│   ├── bun_test.bzl
+│   ├── bun_install.bzl
+│   └── bun_bundle.bzl
+├── examples/
+│   └── basic/
+└── tests/
+    ├── toolchain_test/
+    ├── install_test/
+    ├── binary_test/
+    └── bundle_test/
+```
+
+### 1.2 Toolchain Rule (`toolchain.bzl`)
+```python
+BunToolchainInfo = provider(fields = ["bun_bin", "version"])
+
+bun_toolchain = rule(
+    implementation = _bun_toolchain_impl,
+    attrs = {
+        "bun": attr.label(allow_single_file = True, executable = True, cfg = "exec"),
+        "version": attr.string(),
+    },
+)
+```
+
+### 1.3 Binary Downloads (`repositories.bzl`)
+Use `http_file` to fetch platform-specific Bun binaries:
+- `bun-linux-x64`, `bun-linux-aarch64`
+- `bun-darwin-x64`, `bun-darwin-aarch64`
+- `bun-windows-x64.exe`
+
+Use SHA256 checksums pinned per Bun release. Register via `register_toolchains()`.
+
+**Tests needed:**
+- `toolchain_resolution_test` — assert the correct binary is selected per `--platforms`
+- `bun --version` smoke test via a `sh_test`
+
+---
+
+## Phase 2: `bun_install` (Package Manager)
+
+Replaces `npm install` / `yarn`. This is the highest-leverage rule because every downstream rule depends on it.
+
+### Rule Design
+```python
+bun_install(
+    name = "node_modules",
+    package_json = "//:package.json",
+    bun_lockfile = "//:bun.lockb",
+)
+```
+
+- Runs `bun install --frozen-lockfile` in a sandboxed action
+- Outputs a `node_modules/` directory as a `TreeArtifact`
+- Must be hermetic: no network in actions (vendor or use a repository rule to pre-fetch)
+
+### Key Challenges
+- `bun.lockb` is binary — you need to commit it and treat it as a source file
+- Network access during `bun install` breaks Bazel's sandbox; solve with either:
+  - A **repository rule** that runs install at analysis time (like `npm_install` in rules_nodejs)
+  - Or a **module extension** in Bzlmod
+
+**Tests needed:**
+- Install succeeds with a valid `package.json` + `bun.lockb`
+- Build fails (with a clear error) when `bun.lockb` is out of date
+- Determinism test: run install twice, assert identical output digest
+- Test that `node_modules` is correctly provided to downstream rules
+
+---
+
+## Phase 3: `bun_binary` (Run JS/TS scripts)
+
+```python
+bun_binary(
+    name = "my_script",
+    entry_point = "src/main.ts",
+    node_modules = "//:node_modules",
+    data = glob(["src/**"]),
+)
+```
+
+- Wraps `bun run <entry>` as a Bazel executable
+- Provides `DefaultInfo` with a launcher script
+- Handles both `.js` and `.ts` natively (no transpile step needed)
+
+**Tests needed:**
+- `bun_binary` produces a runnable target (`bazel run`)
+- TypeScript entry points work without separate compilation
+- `data` deps are available at runtime
+- Environment variables pass through correctly
+
+---
+
+## Phase 4: `bun_test` (Test Runner)
+
+```python
+bun_test(
+    name = "my_test",
+    srcs = ["src/foo.test.ts"],
+    node_modules = "//:node_modules",
+)
+```
+
+- Wraps `bun test` with Bazel's test runner protocol
+- Must exit with code 0/non-0 correctly
+- Outputs JUnit XML for `--test_output` compatibility (use `bun test --reporter junit`)
+
+**Tests needed:**
+- Passing test suite returns exit 0
+- Failing test suite returns exit non-0 (Bazel marks as FAILED)
+- Test filtering via `--test_filter` works
+- Coverage via `bun test --coverage` integrates with `bazel coverage`
+- Tests are re-run when source files change (input tracking)
+- Tests are **not** re-run when unrelated files change (cache correctness)
+
+---
+
+## Phase 5: `bun_bundle` (Bundler)
+
+```python
+bun_bundle(
+    name = "app_bundle",
+    entry_points = ["src/index.ts"],
+    node_modules = "//:node_modules",
+    target = "browser",   # or "node", "bun"
+    format = "esm",       # or "cjs", "iife"
+    minify = True,
+)
+```
+
+- Runs `bun build` as a Bazel action
+- Outputs are declared files (JS, sourcemaps, assets)
+- Supports splitting, external packages, define/env vars
+
+**Tests needed:**
+- Output file exists and has non-zero size
+- `minify = True` produces smaller output than `minify = False`
+- `external` packages are not bundled
+- Sourcemaps are generated when requested
+- Build is hermetic: same inputs → identical output digest (content hash)
+- Invalid entry point produces a clear build error (not a cryptic Bazel failure)
+
+---
+
+## Phase 6: `js_library` / `ts_library` (Source Grouping)
+
+Lightweight rules for grouping sources and propagating them through the dep graph:
+
+```python
+ts_library(
+    name = "utils",
+    srcs = glob(["src/**/*.ts"]),
+    deps = [":node_modules"],
+)
+```
+
+**Tests needed:**
+- `deps` correctly propagate transitive sources to `bun_bundle` and `bun_test`
+- Circular dep detection (or at least graceful failure)
+
+---
+
+## Required Tests Summary
+
+| Category | Test |
+|---|---|
+| Toolchain | Correct binary resolves per platform |
+| Toolchain | `bun --version` executes successfully |
+| `bun_install` | Clean install works |
+| `bun_install` | Stale lockfile fails with clear error |
+| `bun_install` | Output is deterministic |
+| `bun_binary` | JS entry point runs |
+| `bun_binary` | TS entry point runs without compile step |
+| `bun_binary` | Data files available at runtime |
+| `bun_test` | Passing tests → exit 0 |
+| `bun_test` | Failing tests → exit non-0 |
+| `bun_test` | Cache hit: unchanged test not re-run |
+| `bun_test` | Cache miss: changed source triggers re-run |
+| `bun_test` | JUnit XML output parseable |
+| `bun_bundle` | Output file produced |
+| `bun_bundle` | Minification reduces output size |
+| `bun_bundle` | Hermetic: identical inputs → identical digest |
+| `bun_bundle` | External packages excluded correctly |
+| Integration | `examples/basic` builds end-to-end with `bazel build //...` |
+| Integration | `bazel test //...` passes all tests |
+
+---
+
+## Development Sequence
+
+```
+1. Toolchain downloads + resolution        ← start here
+2. bun_install (repository rule approach)
+3. bun_binary (simplest runtime rule)
+4. bun_test
+5. bun_bundle
+6. js_library / ts_library
+7. Bzlmod module extension for installs
+8. CI matrix (linux-x64, darwin-arm64, windows)
+9. Docs + examples
+```
+
+---
+
+## Where to Start Right Now
+
+**Day 1:** Copy the pattern from [`rules_go`](https://github.com/bazelbuild/rules_go) or [`aspect-build/rules_js`](https://github.com/aspect-build/rules_js) for toolchain registration. Write `repositories.bzl` that fetches the Bun binary for your current platform only. Write a `sh_test` that calls `bun --version` and asserts it exits 0. Get that green.
+
+**Reference implementations to study:**
+- `aspect-build/rules_js` — best modern reference for JS in Bazel
+- `bazelbuild/rules_nodejs` — older but battle-tested patterns
+- `bazelbuild/rules_python` — excellent toolchain download pattern to copy
+
+The toolchain is the entire foundation. Nothing else is possible without it being solid.

internal/bun_binary.bzl

@@ -0,0 +1,2 @@
+def bun_binary(**_kwargs):
+    fail("bun_binary is not implemented yet")

internal/bun_bundle.bzl

@@ -0,0 +1,2 @@
+def bun_bundle(**_kwargs):
+    fail("bun_bundle is not implemented yet")

internal/bun_install.bzl

@@ -0,0 +1,2 @@
+def bun_install(**_kwargs):
+    fail("bun_install is not implemented yet")

internal/bun_test.bzl

@@ -0,0 +1,2 @@
+def bun_test(**_kwargs):
+    fail("bun_test is not implemented yet")

tests/BUILD.bazel

@@ -0,0 +1 @@
+package(default_visibility = ["//visibility:public"])

tests/toolchain_test/BUILD.bazel

@@ -0,0 +1,10 @@
+sh_test(
+    name = "bun_version_test",
+    srcs = ["toolchain_version.sh"],
+    args = ["$(location @bun_linux_x64//:bun)"],
+    data = ["@bun_linux_x64//:bun"],
+    target_compatible_with = [
+        "@platforms//cpu:x86_64",
+        "@platforms//os:linux",
+    ],
+)

tests/toolchain_test/toolchain_version.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bun_path="$1"
+version="$(${bun_path} --version)"
+
+if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+  echo "Unexpected bun version output: ${version}" >&2
+  exit 1
+fi