Add Bun plugin

.agent/workflows/openspec-apply.md

@@ -0,0 +1,20 @@
+---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

.agent/workflows/openspec-archive.md

@@ -0,0 +1,24 @@
+---
+description: Archive a deployed OpenSpec change and update specs.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

.agent/workflows/openspec-proposal.md

@@ -0,0 +1,25 @@
+---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

.changeset/bun-plugin.md

@@ -0,0 +1,6 @@
+---
+"@arkenv/bun-plugin": minor
+---
+
+Add Bun plugin for build-time environment variable validation and type-safe access, similar to the Vite plugin.
+

.cursor/commands/openspec-proposal.md

@@ -10,6 +10,7 @@ description: Scaffold a new OpenSpec change and validate strictly.
 - Keep changes tightly scoped to the requested outcome.
 - Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
 - Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
 
 **Steps**
 1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.

apps/playgrounds/bun-react/.env.production

@@ -0,0 +1,2 @@
+BUN_PUBLIC_API_URL=https://api.example.com
+BUN_PUBLIC_DEBUG=true

apps/playgrounds/bun-react/bin/build.ts

@@ -0,0 +1,20 @@
+import arkenv from "@arkenv/bun-plugin";
+
+const result = await Bun.build({
+	entrypoints: ["./src/index.html"],
+	outdir: "./dist",
+	sourcemap: true,
+	target: "browser",
+	minify: true,
+	plugins: [arkenv],
+});
+
+if (!result.success) {
+	console.error("Build failed:");
+	for (const log of result.logs) {
+		console.error(log);
+	}
+	process.exit(1);
+}
+
+console.log(`✓ Build succeeded: ${result.outputs.length} files generated`);

apps/playgrounds/bun-react/bun-env.d.ts

@@ -1,17 +1,23 @@
-// Generated by `bun init`
+/// <reference types="bun-types" />
+
+// Import the Env schema type from env.ts
+type ProcessEnvAugmented = import("@arkenv/bun-plugin").ProcessEnvAugmented<
+	typeof import("./src/env").default
+>;
+
+declare namespace NodeJS {
+	interface ProcessEnv extends ProcessEnvAugmented {
+		BUN_PUBLIC_API_URL: string;
+		BUN_PUBLIC_DEBUG: boolean;
+	}
+}
 
 declare module "*.svg" {
-	/**
-	 * A path to the SVG file
-	 */
-	const path: `${string}.svg`;
-	export = path;
+	const content: string;
+	export default content;
 }
 
 declare module "*.module.css" {
-	/**
-	 * A record of class names to their corresponding CSS module classes
-	 */
 	const classes: { readonly [key: string]: string };
-	export = classes;
+	export default classes;
 }

apps/playgrounds/bun-react/bunfig.toml

@@ -1,2 +1,3 @@
 [serve.static]
-env = "BUN_PUBLIC_*"
+env = "BUN_PUBLIC_*"
+plugins = ["@arkenv/bun-plugin"]

apps/playgrounds/bun-react/package.json

@@ -5,11 +5,15 @@
 	"type": "module",
 	"scripts": {
 		"dev": "bun --hot src/index.tsx",
-		"build": "bun build ./src/index.html --outdir=dist --sourcemap --target=browser --minify --define:process.env.NODE_ENV='\"production\"' --env='BUN_PUBLIC_*'",
+		"build": "NODE_ENV=production bun bin/build.ts",
+		"preview": "bun dist/index.html",
 		"start": "NODE_ENV=production bun src/index.tsx",
 		"clean": "rimraf dist node_modules"
 	},
 	"dependencies": {
+		"@arkenv/bun-plugin": "workspace:*",
+		"arkenv": "workspace:*",
+		"arktype": "catalog:",
 		"react": "catalog:",
 		"react-dom": "catalog:"
 	},

apps/playgrounds/bun-react/src/App.tsx

@@ -17,6 +17,29 @@ export function App() {
 				Edit <code>src/App.tsx</code> and save to test HMR
 			</p>
 			<APITester />
+			<table className="env-table">
+				<thead>
+					<tr>
+						<th>Variable</th>
+						<th>Value</th>
+						<th>Type</th>
+					</tr>
+				</thead>
+				<tbody>
+					<tr>
+						<td>BUN_PUBLIC_API_URL</td>
+						<td>{process.env.BUN_PUBLIC_API_URL}</td>
+						<td>{typeof process.env.BUN_PUBLIC_API_URL}</td>
+					</tr>
+					<tr>
+						<td>BUN_PUBLIC_DEBUG</td>
+						<td>{String(process.env.BUN_PUBLIC_DEBUG)}</td>
+						<td>{typeof process.env.BUN_PUBLIC_DEBUG}</td>
+					</tr>
+				</tbody>
+			</table>
+			{/* Print whether we are in "build" or in the dev server */}
+			<p>Mode: {process.env.NODE_ENV}</p>
 		</div>
 	);
 }

apps/playgrounds/bun-react/src/env.ts

@@ -0,0 +1,6 @@
+import { type } from "arkenv";
+
+export default type({
+	BUN_PUBLIC_API_URL: "string",
+	BUN_PUBLIC_DEBUG: "boolean",
+});

apps/playgrounds/bun-react/src/index.css

@@ -185,3 +185,37 @@ code {
 		animation: none !important;
 	}
 }
+
+.env-table {
+	width: 100%;
+	max-width: 600px;
+	margin: 2rem auto;
+	border-collapse: separate;
+	border-spacing: 0;
+	background: #1a1a1a;
+	border-radius: 12px;
+	overflow: hidden;
+	border: 2px solid #fbf0df;
+}
+
+.env-table th,
+.env-table td {
+	padding: 1rem;
+	text-align: left;
+	border-bottom: 1px solid rgba(251, 240, 223, 0.1);
+}
+
+.env-table th {
+	background: rgba(251, 240, 223, 0.1);
+	color: #fbf0df;
+	font-weight: 600;
+}
+
+.env-table td {
+	color: #e0e0e0;
+	font-family: monospace;
+}
+
+.env-table tr:last-child td {
+	border-bottom: none;
+}

apps/playgrounds/bun-react/src/index.tsx

@@ -7,13 +7,13 @@ const server = serve({
 		"/*": index,
 
 		"/api/hello": {
-			async GET(req) {
+			async GET() {
 				return Response.json({
 					message: "Hello, world!",
 					method: "GET",
 				});
 			},
-			async PUT(req) {
+			async PUT() {
 				return Response.json({
 					message: "Hello, world!",
 					method: "PUT",

apps/www/app/layout.tsx

@@ -1,4 +1,4 @@
-import { Banner } from "fumadocs-ui/components/banner";
+import { Banner } from "~/components/banner";
 import "./globals.css";
 import { Analytics } from "@vercel/analytics/next";
 import { SpeedInsights } from "@vercel/speed-insights/next";
@@ -48,18 +48,7 @@ export default function Layout({ children }: { children: ReactNode }) {
 						enableSystem: true,
 					}}
 				>
-					<Banner variant="rainbow" id="vite-support-banner">
-						🎉 Announcing Vite support: check out the&nbsp;
-						<a
-							href="https://arkenv.js.org/docs/vite-plugin"
-							target="_blank"
-							rel="noopener noreferrer"
-							className="underline underline-offset-2 hover:text-blue-500"
-						>
-							new docs
-						</a>
-						!
-					</Banner>
+					<Banner />
 					{children}
 					<SpeedInsights />
 					<Analytics />

apps/www/components/banner.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { Banner as FumadocsBanner } from "fumadocs-ui/components/banner";
+import { useRouter } from "next/navigation";
+
+export function Banner() {
+	const router = useRouter();
+	return (
+		<FumadocsBanner
+			variant="rainbow"
+			id="bun-support-banner"
+			onClick={() => router.push("/docs/bun-plugin")}
+			className="cursor-pointer"
+		>
+			🎉 Official Bun support is here: ArkEnv at build time, fullstack dev
+			server
+		</FumadocsBanner>
+	);
+}

apps/www/components/docs/install-button.tsx

@@ -8,18 +8,24 @@ import { Button } from "~/components/ui/button";
 export function InstallButton() {
 	const pathname = usePathname();
 	const isVitePluginPage = pathname?.includes("/docs/vite-plugin");
+	const isBunPluginPage = pathname?.includes("/docs/bun-plugin");
+
+	let href = "/docs/arkenv/quickstart#install";
+	let label = "Install ArkEnv";
+
+	if (isVitePluginPage) {
+		href = "/docs/vite-plugin#installation";
+		label = "Install ArkEnv Vite plugin";
+	} else if (isBunPluginPage) {
+		href = "/docs/bun-plugin#installation";
+		label = "Install ArkEnv Bun plugin";
+	}
 
 	return (
 		<Button asChild className="w-full cursor-pointer">
-			<Link
-				href={
-					isVitePluginPage
-						? "/docs/vite-plugin#installation"
-						: "/docs/arkenv/quickstart#install"
-				}
-			>
+			<Link href={href}>
 				<Download aria-hidden="true" />
-				{isVitePluginPage ? "Install ArkEnv Vite plugin" : "Install ArkEnv"}
+				{label}
 			</Link>
 		</Button>
 	);