@joinremba/beacon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remba
+
+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,378 @@
+<p align="center">
+  <picture>
+    <img alt="@joinremba/beacon" src="./assets/logo.svg" width="80">
+  </picture>
+  <br>
+  <strong>@joinremba/beacon</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@joinremba/beacon"><img src="https://img.shields.io/npm/v/@joinremba/beacon.svg" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@joinremba/beacon.svg" alt="Licence"></a>
+  <a href="https://github.com/joinremba/beacon/actions/workflows/ci.yml"><img src="https://github.com/joinremba/beacon/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Bun-%3E%3D1.3.1-black?logo=bun" alt="Bun">
+  <img src="https://img.shields.io/badge/TypeScript-6-blue" alt="TypeScript">
+</p>
+
+Beacon helps TypeScript teams boot applications safely by validating environment variables, config, secrets, and runtime feature gates before production breaks.
+
+```sh
+bun add @joinremba/beacon
+bunx beacon init
+bunx beacon check
+```
+
+---
+
+## Quick Start
+
+```ts
+import { createBeacon } from "@joinremba/beacon";
+
+const config = createBeacon({
+  DATABASE_URL: { type: "url", required: true },
+  REDIS_URL: { type: "url", required: true },
+  NODE_ENV: {
+    type: "enum",
+    values: ["development", "test", "staging", "production"],
+    default: "development",
+  },
+  PORT: { type: "port", default: 3000 },
+  API_KEY: { type: "string", required: true, secret: true },
+});
+
+config.ensure();
+
+const dbUrl = config.get<string>("DATABASE_URL");
+```
+
+If any variable is missing or invalid, `ensure()` throws a `ConfigValidationError` with **all issues collected at once** — so you fix everything in a single pass, not iteratively.
+
+---
+
+## Why Beacon?
+
+Most backend projects start with a scattered collection of helper functions for reading env vars, checking types, and remembering which vars are required. This works until:
+
+- A new developer joins and doesn't know which env vars exist
+- A staging environment crashes because a required var was renamed but not documented
+- A secret leaks into an error log because nobody added redaction
+- Your CI pipeline passes locally but fails in production due to config drift
+
+Beacon solves these by giving you a **single source of truth** for your env schema, with built-in validation, secrets redaction, profile support, and CLI tools for generating `.env.example` and checking environments.
+
+---
+
+## Features
+
+- **Schema-based validation** — Define your env schema with simple string types (`"url"`, `"port"`, `"enum"`, etc.) or raw Zod schemas.
+- **Missing variable detection** — All errors are collected and reported together, not one at a time.
+- **Secrets redaction** — Keep secrets out of logs and error messages automatically. Values are replaced with `[REDACTED]`.
+- **Local/staging/production profiles** — Define different schemas per environment.
+- **`.env.example` generation** — Generate a documented `.env.example` from your schema via the CLI.
+- **CLI** — `beacon init` scaffolds config, `beacon check` validates before deploying.
+- **Zero runtime overhead** — Validations run once at boot. After that, access is plain property reads.
+- **Framework-agnostic** — Works with Bun, Node.js, Express, Hono, Fastify, Next.js, Elysia.
+
+---
+
+## CLI
+
+Beacon ships with a CLI for development and CI workflows.
+
+### `beacon init`
+
+Generate a documented `.env.example` from your beacon config:
+
+```sh
+bunx beacon init
+
+# With a production profile:
+bunx beacon init --profile production
+
+# Custom config path:
+bunx beacon init -c ./config/beacon.json -o .env.example.prod
+```
+
+Output includes types, defaults, descriptions, and secret markers for every variable:
+
+```sh
+# PostgreSQL connection string
+# Type: url
+# Required: yes
+# DATABASE_URL=
+
+# HTTP server port
+# Type: port
+# Default: 3000
+PORT=3000
+```
+
+### `beacon check`
+
+Validate your current environment against your schema:
+
+```sh
+bunx beacon check
+
+# With a specific profile:
+bunx beacon check --profile staging
+
+# Custom config:
+bunx beacon check -c ./config/production.json
+```
+
+Output is a colour-coded table:
+
+```sh
+  KEY           STATUS    VALUE
+  ────────────  ────────  ────────────────────
+  DATABASE_URL  pass      postgres://localhost...
+  PORT          pass      Using default value
+  NODE_ENV      pass      Using default value
+  API_KEY       MISSING   Not set
+  LOG_LEVEL     pass      Optional, not set
+  DB_HOST       MISSING   Not set
+                     Did you mean DB_HOSTNAME?
+
+  2 issue(s), 3 pass
+```
+
+Exit codes: `0` if all pass, `1` if any issues found.
+
+### Per-command help
+
+```sh
+beacon help init
+beacon check --help
+```
+
+---
+
+## API Reference
+
+### `createBeacon(schema, options?)`
+
+The default export. Accepts an env schema and optional configuration.
+
+**Parameters**
+
+| Option     | Type                                          | Description                                                 |
+| ---------- | --------------------------------------------- | ----------------------------------------------------------- |
+| `schema`   | `Record<string, SchemaEntry>`                 | Map of environment variable names to field definitions.     |
+| `profile`  | `string`                                      | Active profile name. Merges matching entry from `profiles`. |
+| `profiles` | `Record<string, Record<string, SchemaEntry>>` | Named profile overrides.                                    |
+
+**SchemaEntry** can be either:
+
+**1. String-based** — Simple type names for everyday use:
+
+| Field         | Type        | Default | Description                          |
+| ------------- | ----------- | ------- | ------------------------------------ |
+| `type`        | `FieldType` | —       | The type to validate against.        |
+| `required`    | `boolean`   | `true`  | Whether the variable must be set.    |
+| `default`     | `unknown`   | —       | Default value if not set.            |
+| `secret`      | `boolean`   | `false` | Redact value from errors and logs.   |
+| `values`      | `string[]`  | —       | Allowed values (only for `"enum"`).  |
+| `description` | `string`    | —       | Used when generating `.env.example`. |
+
+| Type      | Zod equivalent                               |
+| --------- | -------------------------------------------- |
+| `string`  | `z.string()`                                 |
+| `url`     | `z.string().url()`                           |
+| `number`  | `z.coerce.number()`                          |
+| `integer` | `z.coerce.number().int()`                    |
+| `boolean` | `"true"` / `"false"` / `"1"` / `"0"` coerced |
+| `port`    | integer 1–65535                              |
+| `enum`    | requires `values[]`                          |
+| `email`   | `z.string().email()`                         |
+| `host`    | `z.string()`                                 |
+
+**2. Zod schema** — Advanced users can pass Zod schemas directly:
+
+```ts
+{
+  PORT: { schema: z.coerce.number().positive().max(9999) },
+  WHITELIST: { schema: z.string().regex(/^[\d,]+$/) },
+}
+```
+
+**Returns**
+
+A config instance with:
+
+| Method / Property | Description                                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ensure()`        | Validates all env vars. Throws `ConfigValidationError` on failure. Returns the config instance for chaining. |
+| `get<T>(key): T`  | Returns the validated value for the given key. Throws if called before `ensure()`.                           |
+| `secret`          | Returns a `Record<string, boolean>` of which keys are marked as secrets.                                     |
+
+### TypeScript Types
+
+```ts
+import type {
+  BeaconOptions,
+  Beacon,
+  SchemaEntry,
+  FieldDefinition,
+  FieldType,
+  ConfigError,
+  ConfigValidationError,
+} from "@joinremba/beacon";
+```
+
+### Config file (`.beaconrc.json`)
+
+Used by the CLI for `init` and `check` commands:
+
+```json
+{
+  "schema": {
+    "DATABASE_URL": {
+      "type": "url",
+      "required": true,
+      "description": "PostgreSQL connection string"
+    },
+    "PORT": { "type": "port", "default": 3000, "description": "HTTP server port" },
+    "NODE_ENV": {
+      "type": "enum",
+      "values": ["development", "production"],
+      "default": "development"
+    },
+    "API_KEY": { "type": "string", "required": true, "secret": true }
+  },
+  "profiles": {
+    "production": {
+      "DB_HOST": { "type": "host", "required": true, "description": "Production DB hostname" }
+    }
+  }
+}
+```
+
+---
+
+## Examples
+
+### Basic env validation
+
+```ts
+import { createBeacon } from "@joinremba/beacon";
+
+const config = createBeacon({
+  NODE_ENV: {
+    type: "enum",
+    values: ["development", "production", "test"],
+    default: "development",
+  },
+  PORT: { type: "port", default: 3000 },
+});
+
+config.ensure();
+console.log(config.get("PORT"));
+```
+
+### With secrets redaction
+
+```ts
+const config = createBeacon({
+  API_KEY: { type: "string", secret: true },
+  DATABASE_URL: { type: "url", secret: true },
+});
+
+config.ensure();
+// Error messages never show API_KEY or DATABASE_URL values
+```
+
+### Custom error handling
+
+```ts
+import { ConfigValidationError } from "@joinremba/beacon";
+
+try {
+  config.ensure();
+} catch (err) {
+  if (err instanceof ConfigValidationError) {
+    for (const issue of err.errors) {
+      console.error(`[${issue.key}] ${issue.message}`);
+    }
+  }
+  process.exit(1);
+}
+```
+
+### Production profile
+
+```ts
+const config = createBeacon(
+  {
+    DB_HOST: { type: "string", default: "localhost" },
+    DB_PORT: { type: "port", default: 5432 },
+  },
+  {
+    profile: "production",
+    profiles: {
+      production: {
+        DB_HOST: { type: "host", required: true },
+        DB_PORT: { type: "port", required: true },
+      },
+    },
+  }
+);
+```
+
+---
+
+## Roadmap
+
+**MVP** (current)
+
+- Typed env validation with string-based types and Zod
+- Missing variable detection (aggregated errors)
+- Secrets redaction in errors and logs
+- Local/staging/production profiles
+- `.env.example` generation via CLI
+- `beacon check` CLI command
+- Coloured CLI output with suggestions
+
+**V1**
+
+- Feature gates from local config
+- Kill-switch flags
+- Encrypted `.env` support
+- Secret rotation checklist
+- CI validation action
+- Docker/Kubernetes env checks
+- Config drift detection
+
+**V2**
+
+- Hosted team secret sync
+- Audit trail for config changes
+- Deployment provider integrations
+- GitHub Actions integration
+- Remba Cloud dashboard
+
+---
+
+## Related Packages
+
+- [@joinremba/catalog](https://github.com/joinremba/catalog) — Production-ready logging and error event layer built on Pino.
+- [@joinremba/gate](https://github.com/joinremba/gate) — API safety layer: validation, responses, idempotency, rate limiting, and API keys.
+
+## Social Preview
+
+For sharing on X (Twitter) and other social platforms, use `assets/og-image.svg` as the repository's social preview image in GitHub repo settings:
+
+1. Go to your repo **Settings** → **Social preview** → **Upload image**
+2. Select `assets/og-image.svg`
+3. Save
+
+This will be used whenever your repo link is shared on social media, Slack, or Discord.
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, development process, and how to submit pull requests.
+
+## License
+
+MIT &mdash; see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@joinremba/beacon",
+  "version": "0.1.0",
+  "description": "Validate environment variables, config, secrets, and runtime feature gates before production breaks.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "beacon": "src/cli.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./cli": {
+      "types": "./src/cli.ts",
+      "import": "./src/cli.ts",
+      "default": "./src/cli.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm",
+    "dev": "bun --watch ./src/index.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "prepublishOnly": "bun run build",
+    "check": "bun lint && bun format:check && bun typecheck && bun test"
+  },
+  "author": {
+    "name": "Benson Isaac",
+    "email": "bensxnisaac@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joinremba/beacon.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joinremba/beacon/issues"
+  },
+  "homepage": "https://github.com/joinremba/beacon#readme",
+  "keywords": [
+    "env",
+    "environment",
+    "config",
+    "validation",
+    "feature-gates",
+    "secrets",
+    "type-safe",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.1"
+  },
+  "dependencies": {
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/cli-config.ts

@@ -0,0 +1,221 @@
+import { z } from "zod";
+import type { SchemaEntry } from "./types";
+
+export interface BeaconConfigFile {
+  schema: Record<string, SchemaEntry>;
+  profile?: string;
+  profiles?: Record<string, Record<string, SchemaEntry>>;
+}
+
+export async function loadConfig(path?: string): Promise<BeaconConfigFile> {
+  const searchPaths = path ? [path] : [".beaconrc.json", "beacon.config.json"];
+
+  for (const searchPath of searchPaths) {
+    const file = Bun.file(searchPath);
+    const exists = await file.exists();
+    if (exists) {
+      const text = await file.text();
+      try {
+        const parsed = JSON.parse(text);
+
+        if (!parsed.schema || typeof parsed.schema !== "object") {
+          throw new Error(`Config file "${searchPath}" must have a "schema" field`);
+        }
+
+        const config: BeaconConfigFile = { schema: parsed.schema };
+
+        if (parsed.profiles) {
+          config.profiles = parsed.profiles;
+        }
+
+        return config;
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          throw new Error(`Invalid JSON in config file "${searchPath}": ${err.message}`);
+        }
+        throw err;
+      }
+    }
+  }
+
+  throw new Error(
+    path
+      ? `Config file not found: ${path}`
+      : "No config file found. Create a .beaconrc.json or pass --config <path>"
+  );
+}
+
+export function generateEnvExample(config: BeaconConfigFile, activeProfile?: string): string {
+  const lines: string[] = [];
+  lines.push("# Environment Variables");
+  lines.push(`# Generated by @joinremba/beacon`);
+  lines.push(`# Profile: ${activeProfile ?? "default"}`);
+  lines.push("");
+
+  const mergedSchema = { ...config.schema };
+
+  if (activeProfile && config.profiles?.[activeProfile]) {
+    Object.assign(mergedSchema, config.profiles[activeProfile]);
+  }
+
+  for (const [key, entry] of Object.entries(mergedSchema)) {
+    if (entry.description) {
+      lines.push(`# ${entry.description}`);
+    }
+
+    const isField = "type" in entry;
+    const isSchema = "schema" in entry;
+
+    if (isField) {
+      const field = entry as {
+        type: string;
+        required?: boolean;
+        default?: unknown;
+        values?: readonly string[];
+        secret?: boolean;
+      };
+      const typeInfo = field.values ? `${field.type} (${field.values.join(" | ")})` : field.type;
+      lines.push(`# Type: ${typeInfo}`);
+      if (field.required !== false) {
+        lines.push(`# Required: yes`);
+      } else {
+        lines.push(`# Required: no`);
+      }
+      if (field.default !== undefined) {
+        lines.push(`# Default: ${field.default}`);
+      }
+      if (field.secret) {
+        lines.push(`# Secret: yes`);
+      }
+
+      if (field.default !== undefined) {
+        lines.push(`${key}=${field.default}`);
+      } else {
+        lines.push(`# ${key}=`);
+      }
+    } else if (isSchema) {
+      const sEntry = entry as { required?: boolean; secret?: boolean; description?: string };
+      if (sEntry.required !== false) {
+        lines.push(`# Required: yes`);
+      } else {
+        lines.push(`# Required: no`);
+      }
+      if (sEntry.secret) {
+        lines.push(`# Secret: yes`);
+      }
+      lines.push(`# ${key}=`);
+    } else {
+      lines.push(`# ${key}=`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+const typeToSchema = (entry: Record<string, unknown>): z.ZodType<unknown> => {
+  const type = entry.type as string;
+  let base: z.ZodType<unknown>;
+
+  switch (type) {
+    case "string":
+    case "host":
+      base = z.string();
+      break;
+    case "url":
+      base = z.string().url();
+      break;
+    case "number":
+      base = z.coerce.number();
+      break;
+    case "integer":
+      base = z.coerce.number().int();
+      break;
+    case "boolean":
+      base = z
+        .string()
+        .transform((v) => v === "true" || v === "1")
+        .pipe(z.boolean());
+      break;
+    case "enum":
+      base = z.enum((entry.values ?? []) as unknown as [string, ...string[]]);
+      break;
+    case "port":
+      base = z.coerce.number().int().min(1).max(65535);
+      break;
+    case "email":
+      base = z.string().email();
+      break;
+    default:
+      base = z.string();
+  }
+
+  if (entry.default !== undefined) {
+    base = base.default(entry.default as string | number | boolean);
+  }
+
+  return base;
+};
+
+export async function runCheck(
+  config: BeaconConfigFile,
+  activeProfile?: string
+): Promise<{
+  results: Array<{ key: string; status: "ok" | "missing" | "invalid"; message: string }>;
+  errors: Array<{ key: string; message: string }>;
+}> {
+  const results: Array<{ key: string; status: "ok" | "missing" | "invalid"; message: string }> = [];
+  const errors: Array<{ key: string; message: string }> = [];
+
+  const mergedSchema = { ...config.schema };
+  if (activeProfile && config.profiles?.[activeProfile]) {
+    Object.assign(mergedSchema, config.profiles[activeProfile]);
+  }
+
+  for (const [key, entry] of Object.entries(mergedSchema)) {
+    const raw = process.env[key];
+    const isField = "type" in entry;
+
+    let required = true;
+    let hasDefault = false;
+
+    if (isField) {
+      const field = entry as { required?: boolean; default?: unknown };
+      required = field.required !== false;
+      hasDefault = field.default !== undefined;
+    } else {
+      const f = entry as { required?: boolean };
+      required = f.required !== false;
+    }
+
+    if (raw === undefined || raw === "") {
+      if (hasDefault) {
+        results.push({ key, status: "ok", message: "Using default value" });
+      } else if (!required) {
+        results.push({ key, status: "ok", message: "Optional, not set" });
+      } else {
+        results.push({ key, status: "missing", message: "Not set" });
+        errors.push({ key, message: "Missing required environment variable" });
+      }
+      continue;
+    }
+
+    try {
+      if (isField) {
+        const schema = typeToSchema(entry as unknown as Record<string, unknown>);
+        schema.parse(raw);
+      }
+      results.push({
+        key,
+        status: "ok",
+        message: `Set (${raw.length > 25 ? raw.substring(0, 25) + "..." : raw})`,
+      });
+    } catch {
+      results.push({ key, status: "invalid", message: `Invalid: "${raw}"` });
+      errors.push({ key, message: `Invalid value: ${raw}` });
+    }
+  }
+
+  return { results, errors };
+}