ezbun 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Shutock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# ezBun
+
+Make running Bun sandboxes easy. `ezbun` is a CLI tool that scans your project for scripts and provides an interactive menu to run them. It also includes built-in environment variable validation and type generation.
+
+## Features
+
+- 🔍 **Auto-discovery**: Automatically finds scripts in your source directory.
+- 🖥️ **Interactive Menu**: Select scripts to run via a CLI interface.
+- 🛡️ **Env Validation**: Validates environment variables using Zod before running scripts.
+- ⚡ **Type Safety**: Automatically generates `env.d.ts` for type-safe `process.env`.
+- 🔄 **Watch Mode**: Supports running scripts in watch mode.
+
+## Installation
+
+```bash
+bun add -D ezbun
+```
+
+## Usage
+
+Add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "ezbun"
+  }
+}
+```
+
+Then run:
+
+```bash
+bun dev
+```
+
+Or run directly with `bunx`:
+
+```bash
+bunx ezbun
+```
+
+### Watch Mode
+
+You can run scripts in watch mode by passing the `--watch` flag:
+
+```bash
+bun dev --watch
+```
+
+## Configuration
+
+Create a `ezbun.config.ts` file in your project root to customize behavior:
+
+```ts
+import { defineConfig } from "ezbun";
+
+export default defineConfig({
+  /** Source directory to scan for scripts */
+  sourceDir: "./src", // default: "./src"
+
+  /** File extensions to include */
+  extensions: ["ts", "tsx", "js", "jsx"], // default: ["ts", "tsx", "js", "jsx", "cjs", "mjs"]
+
+  /** Whether to show a success message after loading env vars */
+  showSuccessMessage: false, // default: false
+});
+```
+
+## Environment Variables
+
+`ezbun` makes handling environment variables easy and type-safe.
+
+1. Create an `env.schema.ts` file in your project root:
+
+```ts
+import { defineEnv, z } from "ezbun";
+
+export default defineEnv({
+  DATABASE_URL: z.url().startsWith("postgres://"),
+  API_KEY: z.string().startsWith("sk-"),
+  PORT: z.coerce.number(),
+});
+```
+
+2. When you run a script via `ezbun`, it will:
+   - Validate `process.env` against your schema.
+   - Print helpful error messages if validation fails.
+   - Automatically generate/update `env.d.ts` for global type definitions.
+
+Now you can use `process.env` with full type safety in your code!
+
+```ts
+// src/index.ts
+console.log(process.env.PORT); // typed as number
+```
+
+## License
+
+MIT

package/cli.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+import prompts from "prompts";
+
+import { loadConfig } from "./utils/config";
+
+export const run = async () => {
+  const config = await loadConfig();
+
+  const args = process.argv.slice(2);
+  const isWatch = args.includes("--watch");
+
+  const extPattern = `*.{${config.extensions.join(",")}}`;
+  const glob = new Bun.Glob(extPattern);
+  const scripts: string[] = [];
+
+  const absoluteSourceDir = `${process.cwd()}/${config.sourceDir}`;
+
+  try {
+    const exitCode = await Bun.spawn(["test", "-d", absoluteSourceDir]).exited;
+    if (exitCode === 0) {
+      for await (const file of glob.scan(absoluteSourceDir)) {
+        scripts.push(file);
+      }
+    } else {
+      console.error(`Source directory ${config.sourceDir} does not exist.`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`Error scanning directory ${absoluteSourceDir}:`, e);
+    process.exit(1);
+  }
+
+  if (scripts.length === 0) {
+    console.error(`No scripts found in ${config.sourceDir}/ directory.`);
+    process.exit(1);
+  }
+
+  const response = await prompts({
+    type: "autocomplete",
+    name: "script",
+    message: "Select a script to run",
+    choices: scripts.map((script) => ({
+      title: script,
+      value: script,
+    })),
+    suggest: async (input, choices) => {
+      const lowercaseInput = input.toLowerCase();
+      return choices.filter((choice) =>
+        choice.title.toLowerCase().includes(lowercaseInput),
+      );
+    },
+  });
+
+  if (!response.script) {
+    console.log("No script selected.");
+    process.exit(0);
+  }
+
+  const selectedScript = response.script;
+
+  const preloadPath = `${import.meta.dir}/preload.ts`;
+
+  const cmd = [
+    "bun",
+    "--bun",
+    ...(isWatch ? ["--watch"] : []),
+    "--preload",
+    preloadPath,
+    `${absoluteSourceDir}/${selectedScript}`,
+    ...args.filter((arg) => arg !== "--watch"),
+  ];
+
+  console.log(
+    `\nRunning ${selectedScript} ${isWatch ? "(watch mode)" : ""}...\n`,
+  );
+
+  const proc = Bun.spawn({
+    cmd,
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+
+  await proc.exited;
+  process.exit(0);
+};
+
+run();

package/index.ts

@@ -0,0 +1,2 @@
+export { type Config, defineConfig } from "./utils/config";
+export { defineEnv, z } from "./utils/env";

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ezbun",
+  "description": "Make run bund sandboxes easy",
+  "author": "Denis Sh. <yo@shutock.com>",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "sandbox"
+  ],
+  "files": [
+    "*.ts",
+    "utils"
+  ],
+  "type": "module",
+  "version": "0.1.0",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "bin": "./cli.ts",
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@config/eslint": "*",
+    "@config/typescript": "*",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^22.15.3",
+    "@types/prompts": "^2.4.9",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "bun": "^1.3.5"
+  }
+}

package/preload.ts

@@ -0,0 +1,3 @@
+import { validateEnv } from "./utils/env";
+
+await validateEnv();

package/utils/config.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+const schema = z.object({
+  sourceDir: z.string().default("./src"),
+  extensions: z
+    .array(z.string())
+    .default(["ts", "tsx", "js", "jsx", "cjs", "mjs"]),
+  showSuccessMessage: z.boolean().default(false),
+});
+
+export type Config = {
+  /** Source directory
+   * @default "./src"
+   */
+  sourceDir?: string;
+  /** File extensions to parse
+   * @default ["ts", "tsx", "js", "jsx", "cjs", "mjs"]
+   */
+  extensions?: string[];
+  /** Whether to print a success message after loading the envs
+   * @default true
+   */
+  showSuccessMessage?: boolean;
+};
+
+export const loadConfig = async () => {
+  const configPath = `${process.cwd()}/ezbun.config.ts`;
+  const configFile = Bun.file(configPath);
+
+  if (await configFile.exists()) {
+    try {
+      const configModule = await import(configPath);
+      return schema.parse(configModule.default || {});
+    } catch (error) {
+      console.error("Error loading ezbun.config.ts:", error);
+      throw error;
+    }
+  }
+
+  return schema.parse({});
+};
+
+export const defineConfig = (config: Config) => config;

package/utils/console.ts

@@ -0,0 +1,4 @@
+export const red = (message: string) => `\x1b[31m${message}\x1b[0m`;
+export const green = (message: string) => `\x1b[32m${message}\x1b[0m`;
+export const bold = (message: string) => `\x1b[1m${message}\x1b[0m`;
+export const icon = { check: "✔", cross: "⨯" };

package/utils/env.ts

@@ -0,0 +1,65 @@
+import z from "zod";
+
+import { loadConfig } from "./config";
+import { bold, green, icon, red } from "./console";
+
+export { z };
+
+export const defineEnv = <T extends z.ZodRawShape>(schema: T) =>
+  z.object(schema);
+
+export const loadUserEnv = async () => {
+  try {
+    const schemaPath = `${process.cwd()}/env.schema.ts`;
+    const module = await import(schemaPath);
+    return module.default as z.ZodObject;
+  } catch {
+    return null;
+  }
+};
+
+export const validateEnv = async () => {
+  const envSchema = await loadUserEnv();
+  if (!envSchema) return;
+
+  const envValidation = envSchema.safeParse(process.env);
+
+  if (envValidation.error) {
+    const message = [
+      `${red(icon.cross)} ${bold("Error in loading environment variables:")}`,
+      ...envValidation.error.issues.map(
+        ({ message, path }) =>
+          `  ${path.map((p) => red(String(p))).join(", ")}: ${message}`,
+      ),
+    ].join("\n");
+
+    console.error(message);
+    process.exit(1);
+  }
+
+  await generateEnvDts();
+
+  const { showSuccessMessage } = await loadConfig();
+  if (!showSuccessMessage) return;
+
+  return console.info(
+    `${green(icon.check)} ${bold("Environment variables loaded successfully")}\n`,
+  );
+};
+
+const generateEnvDts = async () => {
+  const dtsPath = `${process.cwd()}/env.d.ts`;
+
+  const content = `import type { z } from "zod";
+
+import type envSchema from "./env.schema";
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv extends Omit<z.infer<typeof envSchema>, "NODE_ENV"> {}
+  }
+}
+`;
+
+  await Bun.write(dtsPath, content);
+};

package/utils/schema.ts

@@ -0,0 +1,14 @@
+import z from "zod";
+
+export const defineEnv = <T extends z.ZodRawShape>(schema: T) =>
+  z.object(schema);
+
+export const loadUserEnv = async () => {
+  try {
+    const schemaPath = `${process.cwd()}/env.schema.ts`;
+    const module = await import(schemaPath);
+    return module.default as z.ZodObject;
+  } catch {
+    return null;
+  }
+};