@joinremba/beacon 0.5.0 → 0.5.2

package/README.md

@@ -6,6 +6,10 @@
   <strong>@joinremba/beacon</strong>
 </p>
 
+<p align="center">
+  Validate environment variables, config, secrets, and runtime feature gates before production breaks.
+</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="License"></a>
@@ -14,32 +18,19 @@
   <img src="https://img.shields.io/badge/TypeScript-6-blue" alt="TypeScript">
 </p>
 
-Beacon validates environment variables, config, secrets, and runtime feature gates before production breaks. Define your schema once — get type coercion, secret redaction, profile merging, per-command CLI tooling, and AES-256-GCM encryption for your `.env` files.
-
-```sh
-bun add @joinremba/beacon
-bunx beacon init
-bunx beacon check
-```
-
 ---
 
 ## Features
 
-- **Schema-based validation** with type coercion — `string`, `url`, `number`, `integer`, `boolean`, `enum`, `port`, `host`, `email`
-- **Custom Zod schemas** for advanced validation rules
-- **Aggregated error reporting** — all errors collected at once, not fail-fast
-- **Secret redaction** — `[REDACTED]` in error messages and CLI output
-- **Default values** for optional variables
-- **Profile merging** — define different schemas per environment (dev, staging, production)
-- **Feature gates** with percentage-based rollout (deterministic djb2 hash)
-- **Kill switches** — `KILL_<NAME>` env var takes priority over feature gates
-- **Environment overrides** — `FEATURE_<NAME>` env var toggles features at runtime
-- **Remote config** via `client` option — connect to Nexus backend
-- **`strict: false` mode** for tests and bootstrap
-- **CLI commands** — `init`, `check`, `encrypt`, `decrypt`, `rotate`, `drift`, `docker`
-- **AES-256-GCM encryption** for `.env` files
-- **Zero runtime dependencies** beyond `zod` and `@joinremba/core`
+- **Schema-based validation** — Define env vars with simple string types (`"url"`, `"port"`, `"enum"`, etc.) or raw Zod schemas.
+- **Aggregated errors** — All missing/invalid variables are reported at once, not one at a time.
+- **Secrets redaction** — Values marked `secret: true` are automatically replaced with `[REDACTED]` in errors and CLI output.
+- **Profile overrides** — Define per-environment schemas (development, staging, production) with inheritance.
+- **Feature gates & kill switches** — Runtime toggles with env-var overrides and deterministic rollout hashing.
+- **CLI tool** — `beacon init` generates `.env.example`, `beacon check` validates the runtime environment, `beacon drift` detects config drift.
+- **Encrypted .env** — AES-256-GCM encrypt/decrypt `.env` files for safe committing.
+- **Remote config** — Fetches config from the Remba cloud via `@joinremba/core` client with local fallback.
+- **TypeScript-first** — Strict types, generic getter, full type exports.
 
 ---
 
@@ -56,302 +47,220 @@ bun add @joinremba/beacon
 ```ts
 import { createBeacon } from "@joinremba/beacon";
 
-const beacon = createBeacon({
-  PORT:          { type: "port", default: 3000 },
-  DATABASE_URL:  { type: "url", secret: true },
-  NODE_ENV:      { type: "enum", values: ["dev", "prod"], default: "dev" },
-  FEATURE_NEW_CHECKOUT: { type: "boolean", default: "false" },
+const config = createBeacon({
+  DATABASE_URL: { type: "url", required: true },
+  REDIS_URL: { type: "url", required: true },
+  PORT: { type: "port", default: 3000 },
+  NODE_ENV: { type: "enum", values: ["development", "production"], default: "development" },
+  API_KEY: { type: "string", required: true, secret: true },
 });
 
-await beacon.ensure();
-const port = beacon.get<number>("PORT");         // 3000
-const dbUrl = beacon.get<string>("DATABASE_URL"); // process.env value
+await config.ensure();
+
+const dbUrl = config.get<string>("DATABASE_URL");
+const port = config.get<number>("PORT");
 ```
 
-If any variable is missing or invalid, `ensure()` throws a `ConfigValidationError` with **all issues reported at once** — so you fix everything in a single pass.
+If any required variable is missing or invalid, `ensure()` throws a `ConfigValidationError` with **all** issues collected at once — fix everything in a single pass.
 
 ---
 
-## Schema Field Types
+## Schema Types
 
-| Type      | Description                          | Coercion / Validation                  |
-|-----------|--------------------------------------|----------------------------------------|
-| `string`  | Any string value                     | `z.string()`                           |
-| `url`     | Valid URL                            | `z.string().url()`                     |
-| `number`  | Coerced to number                    | `z.coerce.number()`                    |
-| `integer` | Coerced to integer                   | `z.coerce.number().int()`              |
-| `boolean` | `true` / `false` / `1` / `0` / `yes` / `no` | String transform + `z.boolean()` |
-| `enum`    | Must match one of `values[]`         | `z.enum(values)`                       |
-| `port`    | Integer 1–65535                      | `z.coerce.number().int().min(1).max(65535)` |
-| `host`    | Hostname string                      | `z.string()`                           |
-| `email`   | Valid email format                   | `z.string().email()`                   |
+Each field in the schema can be defined with a `type` string. Beacon coerces and validates the raw `process.env` value accordingly.
 
-### Schema Entry Options
+| Type      | Validation                                              | Coercion                                    | Example                                |
+| --------- | ------------------------------------------------------- | ------------------------------------------- | -------------------------------------- |
+| `string`  | Any string                                              | —                                           | `{ type: "string" }`                   |
+| `host`    | Any string (alias for `string`)                         | —                                           | `{ type: "host" }`                     |
+| `url`     | Valid URL                                               | —                                           | `{ type: "url" }`                      |
+| `number`  | Finite number                                           | `z.coerce.number()`                         | `{ type: "number" }`                   |
+| `integer` | Integer                                                 | `z.coerce.number().int()`                   | `{ type: "integer" }`                  |
+| `port`    | Integer in range 1–65535                                | `z.coerce.number().int().min(1).max(65535)` | `{ type: "port", default: 3000 }`      |
+| `boolean` | `"true"` / `"false"` / `"1"` / `"0"` / `"yes"` / `"no"` | String transform                            | `{ type: "boolean" }`                  |
+| `enum`    | Must be one of `values[]`                               | `z.enum(values)`                            | `{ type: "enum", values: ["a", "b"] }` |
+| `email`   | Valid email                                             | `z.string().email()`                        | `{ type: "email" }`                    |
 
 ```ts
-{ type: "url", required: true, default: "https://localhost", secret: true, description: "DB connection string" }
+const config = createBeacon({
+  APP_NAME: { type: "string", default: "my-app" },
+  DATABASE_URL: { type: "url", required: true },
+  WORKERS: { type: "integer", default: 4 },
+  PORT: { type: "port", default: 3000 },
+  SUPPORT_EMAIL: { type: "email", required: true },
+  LOG_LEVEL: { type: "enum", values: ["debug", "info", "warn", "error"], default: "info" },
+  ENABLE_METRICS: { type: "boolean", default: false },
+});
 ```
 
-| Field         | Type        | Default  | Description                              |
-|---------------|-------------|----------|------------------------------------------|
-| `type`        | `FieldType` | —        | The field type to validate against.      |
-| `required`    | `boolean`   | `true`   | Whether the variable must be set.        |
-| `default`     | `unknown`   | —        | Default value when not set in env.       |
-| `secret`      | `boolean`   | `false`  | Redact value from errors and CLI output. |
-| `values`      | `string[]`  | —        | Allowed values (for `"enum"` type only). |
-| `description` | `string`    | —        | Used when generating `.env.example`.     |
-
-### Custom Zod Schemas
-
-For advanced validation, pass a Zod schema directly:
+You can also pass raw **Zod schemas** directly for custom validation:
 
 ```ts
 import { z } from "zod";
 
-const beacon = createBeacon({
-  PORT:      { schema: z.coerce.number().positive().max(9999) },
+const config = createBeacon({
   WHITELIST: { schema: z.string().regex(/^[\d,]+$/) },
+  TIMEOUT: { schema: z.coerce.number().positive().max(30000) },
 });
 ```
 
 ---
 
-## Feature Gates
+## `.ensure()`
 
-Toggle features on and off without redeploying. Define gates in the `features` option and check them with `isEnabled()`.
+Validates every variable in the schema against the current `process.env`. Must be called before any `get()` call.
 
 ```ts
-const beacon = createBeacon(
-  { DATABASE_URL: { type: "url" } },
-  {
-    features: {
-      newDashboard:      { enabled: true },
-      darkMode:          { enabled: false },
-      gradualRollout:    { enabled: true, rollout: 0.5 },
-    },
-    killSwitches: {
-      brokenFeature: true,          // force-disabled
-    },
-  }
-);
-
-beacon.isEnabled("newDashboard");    // true
-beacon.isEnabled("darkMode");        // false
-beacon.isEnabled("gradualRollout");  // true for ~50% of instances (deterministic hash)
-beacon.isEnabled("brokenFeature");   // false — killed
-beacon.isKilled("brokenFeature");    // true
+await config.ensure();
 ```
 
-### `FeatureGate`
-
-| Option        | Type      | Default  | Description                                               |
-|---------------|-----------|----------|-----------------------------------------------------------|
-| `enabled`     | `boolean` | `false`  | Whether the gate is on by default.                        |
-| `rollout`     | `number`  | —        | Fraction of instances (0–1) that see the feature. Uses deterministic djb2 hash. |
-| `description` | `string`  | —        | Human-readable description.                               |
+**Behavior:**
 
-### Environment Overrides
+| Condition                         | strict: true (default)         | strict: false                |
+| --------------------------------- | ------------------------------ | ---------------------------- |
+| Required var present, valid       | Passes                         | Passes                       |
+| Required var missing              | `ConfigValidationError` thrown | Silently skipped             |
+| Required var present, invalid     | `ConfigValidationError` thrown | Silently skipped             |
+| Optional var not set, has default | Default applied                | Default applied              |
+| Optional var not set, no default  | Skipped                        | Skipped                      |
+| Remote config available           | Merged into validated values   | Merged into validated values |
 
-Set `FEATURE_<NAME>` in the environment to override any feature gate at runtime. CamelCase names are converted to `SCREAMING_SNAKE_CASE` (`newDashboard` → `FEATURE_NEW_DASHBOARD`). Accepted truthy values: `true`, `1`, `yes`.
+Errors are aggregated into a single `ConfigValidationError` (extends `AggregateError`). Access individual issues via `err.errors`:
 
-```sh
-FEATURE_DARK_MODE=true bun start
-FEATURE_NEW_DASHBOARD=false bun start
-```
-
-### Kill Switches
-
-Kill switches **always take priority** over feature gates. Set them via the `killSwitches` option or the `KILL_<NAME>` env var.
+```ts
+import { ConfigValidationError } from "@joinremba/beacon";
 
-```sh
-KILL_BROKEN_FEATURE=true bun start
+try {
+  await config.ensure();
+} catch (err) {
+  if (err instanceof ConfigValidationError) {
+    for (const issue of err.errors) {
+      console.error(`[${issue.key}] ${issue.message}`);
+    }
+  }
+  process.exit(1);
+}
 ```
 
-```ts
-beacon.isKilled("brokenFeature"); // true
-beacon.isEnabled("brokenFeature"); // false — killed overrides enabled
-```
+The `ensure({ strict: false })` mode is useful during testing or bootstrap when some env vars may not yet be configured.
 
 ---
 
-## Remote Config
+## `.getAll()`
 
-Beacon can merge in remote configuration entries from a Nexus backend before local validation. Pass a `Client` from `@joinremba/core` via the `client` option.
+Returns a `Record<string, unknown>` of **all** resolved values after `ensure()` completes.
 
 ```ts
-import { createBeacon } from "@joinremba/beacon";
-import { createClient } from "@joinremba/core";
-
-const beacon = createBeacon(
-  {
-    PORT: { type: "port", default: 3000 },
-  },
-  {
-    client: createClient({ apiKey: "api_core_live_..." }),
-  }
-);
-
-await beacon.ensure();
-// Remote entries fill gaps not defined in the schema.
-// Schema entries always take priority over remote values.
-// Network failures fall back silently to local-only validation.
+await config.ensure();
+const all = config.getAll();
+// { DATABASE_URL: "postgres://...", PORT: 3000, NODE_ENV: "development", ... }
 ```
 
----
-
-## CLI Commands
-
-Beacon ships with a CLI for development, CI, and ops workflows.
-
-| Command      | Description                                      |
-|--------------|--------------------------------------------------|
-| `init`       | Generate `.env.example` from your config file.   |
-| `check`      | Validate current environment against schema.     |
-| `encrypt`    | Encrypt `.env` (AES-256-GCM) for safe committing.|
-| `decrypt`    | Decrypt `.env.encrypted` back to plaintext.      |
-| `rotate`     | Print step-by-step secret rotation checklist.    |
-| `drift`      | Detect config drift — schema vs. actual env.     |
-| `docker`     | Validate env in Docker / Kubernetes contexts.    |
-
-### `beacon init`
-
-```sh
-bunx beacon init                              # generate .env.example
-bunx beacon init --profile production         # with profile merge
-bunx beacon init --all-profiles               # generate for every profile
-bunx beacon init -c ./config/beacon.json -o .env.example.prod
-```
+Useful for debugging, logging startup configuration, or passing the full config object to subsystems.
 
-Output includes types, defaults, descriptions, and secret markers:
+---
 
-```
-# PostgreSQL connection string
-# Type: url
-# Required: yes
-# DATABASE_URL=
-
-# HTTP server port
-# Type: port
-# Default: 3000
-PORT=3000
-```
+## `.get<T>(key)`
 
-### `beacon check`
+Type-safe accessor for individual validated values. Call `.get<T>(key)` with an optional generic type parameter.
 
-```sh
-bunx beacon check                             # validate env
-bunx beacon check --profile staging           # with profile
-bunx beacon check -c ./config/production.json
+```ts
+const port = config.get<number>("PORT"); // type: number
+const dbUrl = config.get<string>("DATABASE_URL"); // type: string
+const debug = config.get<boolean>("DEBUG"); // type: boolean
 ```
 
-Colour-coded table output:
+Throws `ConfigError` if:
 
-```
-  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?
-  ✓ 3 pass, 2 issue(s)
-```
-
-Exit codes: `0` if all pass, `1` if any issues.
+- Called before `ensure()` — `"Call beacon.ensure() before accessing config values"`
+- Key doesn't exist in the schema — `"Unknown config key: <key>"`
 
-### `beacon encrypt` / `beacon decrypt`
+---
 
-```sh
-# Encrypt .env → .env.encrypted
-BEACON_ENCRYPTION_KEY=your-key beacon encrypt
+## Secrets
 
-# Decrypt back to plaintext
-BEACON_ENCRYPTION_KEY=your-key beacon decrypt
+Mark sensitive fields with `secret: true` to prevent their values from appearing in error messages, CLI output, or logs.
 
-# Custom paths
-beacon encrypt -i .env.prod -o .env.prod.encrypted --key "your-key"
-beacon decrypt -i .env.prod.encrypted -o .env.prod --key "your-key"
+```ts
+const config = createBeacon({
+  API_KEY: { type: "string", required: true, secret: true },
+  DATABASE_URL: { type: "url", secret: true },
+});
 ```
 
-Uses **AES-256-GCM** with HKDF-SHA256 key derivation. The key can be passed via `--key` flag or `BEACON_ENCRYPTION_KEY` environment variable.
-
-### `beacon rotate`
+When a secret value fails validation, the error message shows `[REDACTED]` instead of the actual value:
 
-Prints a step-by-step checklist for safely rotating secrets (generate → deploy alongside → update consumers → verify → revoke → audit).
-
-```sh
-bunx beacon rotate
 ```
-
-### `beacon drift`
-
-Detects config drift — missing required variables, type mismatches, and unexpected enum values.
-
-```sh
-bunx beacon drift
-bunx beacon drift --profile production
+Environment variable API_KEY=[REDACTED]: Invalid value
 ```
 
-### `beacon docker`
-
-Detects Docker and Kubernetes runtimes, checks common container env vars, and runs a full schema validation.
+The secret metadata is also accessible at runtime:
 
-```sh
-bunx beacon docker
-bunx beacon docker --profile staging
+```ts
+config.secret; // { API_KEY: true, DATABASE_URL: true }
 ```
 
 ---
 
-## Profiles
+## NODE_ENV Handling
 
-Define different schemas per environment using the `profiles` option. The active profile is selected via `profile`.
+Beacon handles `NODE_ENV` like any other env var — define it in your schema with an `enum` type and a default:
 
 ```ts
-const beacon = createBeacon(
-  {
-    DB_HOST: { type: "string", default: "localhost" },
-    DB_PORT: { type: "port", default: 5432 },
+const config = createBeacon({
+  NODE_ENV: {
+    type: "enum",
+    values: ["development", "test", "staging", "production"],
+    default: "development",
   },
-  {
-    profile: "production",
-    profiles: {
-      production: {
-        DB_HOST: { type: "host", required: true },
-        DB_PORT: { type: "port", required: true },
-      },
-      staging: {
-        DB_HOST: { type: "host", required: true },
-      },
-    },
-  }
-);
+});
 ```
 
-Profile entries are **merged into the base schema** — they can add new variables, override types, change defaults, or toggle required flags.
+**Defaults behavior:**
 
-You can also use profiles with the CLI:
+- When an env var is not set and has a `default`, the default value is used silently.
+- When an env var is not set, has no default, but `required: false`, it is silently skipped.
+- When an env var is not set, has no default, and `required: true` (the default), it fails validation.
 
-```sh
-bunx beacon init --profile production
-bunx beacon check --profile staging
-```
+This means you can safely deploy with minimal env vars during development as long as sensible defaults are provided.
 
-### Config file (`.beaconrc.json`)
+---
+
+## `.beaconrc.json` (CLI Config File)
+
+The CLI reads schema, profiles, and features from a JSON config file. It looks for `.beaconrc.json` or `beacon.config.json` in the project root.
 
 ```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 }
+    "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", "staging", "production"],
+      "default": "development"
+    },
+    "API_KEY": {
+      "type": "string",
+      "required": true,
+      "secret": true,
+      "description": "API signing key"
+    }
   },
   "profiles": {
     "production": {
       "DB_HOST": { "type": "host", "required": true, "description": "Production DB hostname" }
+    },
+    "staging": {
+      "DB_HOST": { "type": "host", "required": true, "description": "Staging DB hostname" }
     }
   },
   "features": {
@@ -361,128 +270,176 @@ bunx beacon check --profile staging
 }
 ```
 
-The CLI auto-discovers `.beaconrc.json` or `beacon.config.json`.
+**CLI commands:**
 
----
+```sh
+# Generate .env.example from the config
+bunx beacon init
+bunx beacon init --profile production
+bunx beacon init --all-profiles
 
-## Error Handling
+# Validate current environment against schema
+bunx beacon check
+bunx beacon check --profile staging
 
-All validation errors are **collected and thrown together** as a single `ConfigValidationError` (an `AggregateError` subclass). Each individual issue is a `ConfigError` with the offending key and a human-readable message.
+# Detect config drift (missing vars, type mismatches)
+bunx beacon drift
+bunx beacon drift --profile production
 
-```ts
-import { createBeacon, ConfigValidationError, ConfigError } from "@joinremba/beacon";
+# Encrypt/decrypt .env files for safe committing
+BEACON_ENCRYPTION_KEY=... beacon encrypt
+BEACON_ENCRYPTION_KEY=... beacon decrypt
 
-try {
-  await beacon.ensure();
-} catch (err) {
-  if (err instanceof ConfigValidationError) {
-    for (const issue of err.errors) {
-      console.error(`[${issue.key}] ${issue.message}`);
-      // issue.redacted — true if the value was hidden
-    }
-  }
-}
+# Validate env in Docker/Kubernetes
+bunx beacon docker
+
+# Print secret rotation checklist
+bunx beacon rotate
 ```
 
-### `strict: false` mode
+---
 
-Pass `{ strict: false }` to `ensure()` to silently skip missing required variables without throwing. Useful in test environments or bootstrap scripts.
+## Configuration Reference
 
-```ts
-await beacon.ensure({ strict: false });
-// Missing required vars are skipped instead of throwing
-```
+### `createBeacon(schema, options?)`
+
+| Option         | Type                                          | Default | Description                                               |
+| -------------- | --------------------------------------------- | ------- | --------------------------------------------------------- |
+| `schema`       | `Record<string, SchemaEntry>`                 | —       | Map of env var names to field definitions (required).     |
+| `profile`      | `string`                                      | —       | Active profile name. Merges matching entry from profiles. |
+| `profiles`     | `Record<string, Record<string, SchemaEntry>>` | —       | Named profile overrides. Keyed by profile name.           |
+| `features`     | `Record<string, FeatureGate>`                 | —       | Feature gate definitions for `isEnabled()`.               |
+| `killSwitches` | `Record<string, boolean>`                     | —       | Kill-switch flags. Overrides feature gates.               |
+| `client`       | `Client` (from `@joinremba/core`)             | —       | Remote config client. Fetches config from cloud.          |
+
+### `SchemaEntry`
+
+**String-based field definition:**
+
+| Field         | Type        | Default | Description                                                                               |
+| ------------- | ----------- | ------- | ----------------------------------------------------------------------------------------- |
+| `type`        | `FieldType` | —       | One of: `string`, `url`, `number`, `integer`, `boolean`, `port`, `enum`, `host`, `email`. |
+| `required`    | `boolean`   | `true`  | Whether the variable must be present in env.                                              |
+| `default`     | `unknown`   | —       | Default value when not set.                                                               |
+| `secret`      | `boolean`   | `false` | Redact value from errors, logs, and CLI output.                                           |
+| `values`      | `string[]`  | —       | Allowed values (required for `"enum"` type).                                              |
+| `description` | `string`    | —       | Human-readable description. Used in `.env.example`.                                       |
+
+**Zod-based field definition:**
+
+| Field         | Type        | Default | Description                                     |
+| ------------- | ----------- | ------- | ----------------------------------------------- |
+| `schema`      | `z.ZodType` | —       | A Zod schema for custom validation logic.       |
+| `required`    | `boolean`   | `true`  | Whether the variable must be present in env.    |
+| `secret`      | `boolean`   | `false` | Redact value from errors, logs, and CLI output. |
+| `description` | `string`    | —       | Human-readable description.                     |
+
+### Returned Beacon instance
+
+| Method / Property    | Returns                   | Description                                |
+| -------------------- | ------------------------- | ------------------------------------------ |
+| `ensure(options?)`   | `Promise<Beacon>`         | Validates all env vars. Throws on failure. |
+| `getAll()`           | `Record<string, unknown>` | Returns all resolved values.               |
+| `get<T>(key)`        | `T`                       | Returns a single typed value.              |
+| `secret`             | `Record<string, boolean>` | Which keys are marked as secrets.          |
+| `isEnabled(feature)` | `boolean`                 | Checks if a feature gate is enabled.       |
+| `isKilled(feature)`  | `boolean`                 | Checks if a kill switch is active.         |
+
+### `EnsureOptions`
+
+| Option   | Type      | Default | Description                                      |
+| -------- | --------- | ------- | ------------------------------------------------ |
+| `strict` | `boolean` | `true`  | When `false`, missing required vars are skipped. |
 
-### Secret Redaction
+### `FeatureGate`
 
-When a field is marked `{ secret: true }`, its value is replaced with `[REDACTED]` in all error messages and CLI output — never leaked into logs or terminal.
+| Option        | Type      | Default | Description                                        |
+| ------------- | --------- | ------- | -------------------------------------------------- |
+| `enabled`     | `boolean` | `false` | Whether the feature is on by default.              |
+| `rollout`     | `number`  | —       | Rollout percentage (0–1). Uses deterministic hash. |
+| `description` | `string`  | —       | Human-readable description.                        |
 
 ---
 
-## Encryption
-
-Beacon provides AES-256-GCM encryption for `.env` files via the CLI and programmatic API.
+## TypeScript
 
-### Programmatic
+Beacon ships with strict TypeScript types. All public APIs are fully typed.
 
 ```ts
-import { encryptEnv, decryptEnv } from "@joinremba/beacon";
-
-const encrypted = await encryptEnv("DATABASE_URL=postgres://...", "your-key");
-const decrypted = await decryptEnv(encrypted, "your-key");
+import { createBeacon } from "@joinremba/beacon";
+import type {
+  Beacon,
+  BeaconOptions,
+  SchemaEntry,
+  FieldDefinition,
+  FieldType,
+  FeatureGate,
+  EnsureOptions,
+  ConfigError,
+  ConfigValidationError,
+} from "@joinremba/beacon";
 ```
 
-### CLI
+**Generic inference with `.get<T>()`:**
 
-```sh
-beacon encrypt -i .env -o .env.encrypted --key "your-key"
-beacon decrypt -i .env.encrypted -o .env --key "your-key"
-```
+```ts
+const config = createBeacon({
+  PORT: { type: "port", default: 3000 },
+  DEBUG: { type: "boolean", default: false },
+});
 
-The key can also be set via `BEACON_ENCRYPTION_KEY` env var. Key derivation uses HKDF-SHA256 with a 32-byte salt.
+await config.ensure();
+
+const port = config.get<number>("PORT"); // inferred as number
+const debug = config.get<boolean>("DEBUG"); // inferred as boolean
+```
 
 ---
 
-## API Reference
+## Integration with `@joinremba/core`
 
-### `createBeacon(schema, options?)`
+Beacon can fetch remote configuration from the Remba cloud by passing a `Client` instance from `@joinremba/core`.
 
-| Parameter | Type                                    | Description                              |
-|-----------|-----------------------------------------|------------------------------------------|
-| `schema`  | `Record<string, SchemaEntry>`           | Map of env var names to field defs.      |
-| `options` | `BeaconOptions`                         | Optional config (features, profiles, etc.) |
-
-#### `BeaconOptions`
+```ts
+import { createBeacon } from "@joinremba/beacon";
+import { createClient } from "@joinremba/core";
 
-| Option         | Type                                             | Description                                      |
-|----------------|--------------------------------------------------|--------------------------------------------------|
-| `profile`      | `string`                                         | Active profile name.                              |
-| `profiles`     | `Record<string, Record<string, SchemaEntry>>`    | Named profile overrides.                          |
-| `features`     | `Record<string, FeatureGate>`                    | Feature gate definitions.                         |
-| `killSwitches` | `Record<string, boolean>`                        | Force-disabled features.                          |
-| `client`       | `Client` (from `@joinremba/core`)                | Remote config client.                             |
+const client = createClient({
+  apiKey: "api_core_live_abc123",
+});
 
-#### `Beacon` (returned by `createBeacon`)
+const config = createBeacon(
+  {
+    LOCAL_VAR: { type: "string", default: "local-fallback" },
+    PORT: { type: "port", default: 3000 },
+  },
+  { client }
+);
 
-| Method / Property              | Description                                                       |
-|--------------------------------|-------------------------------------------------------------------|
-| `ensure(options?)`             | Validates all env vars. Throws `ConfigValidationError` on failure. Returns the beacon instance. |
-| `get<T>(key)`                  | Returns the validated, coerced value. Throws if called before `ensure()`. |
-| `secret`                       | `Record<string, boolean>` — which keys are marked as secrets.     |
-| `isEnabled(feature)`           | Checks if a feature gate is enabled. Respects kill switches, env overrides, and rollout. |
-| `isKilled(feature)`            | Checks if a feature is force-disabled (kill switch or env).       |
+await config.ensure();
+```
 
-#### `EnsureOptions`
+**How remote config merging works:**
 
-| Option   | Type      | Default | Description                                              |
-|----------|-----------|---------|----------------------------------------------------------|
-| `strict` | `boolean` | `true`  | When `false`, missing required vars are skipped silently. |
+1. On `ensure()`, beacon calls `client.getConfig()`.
+2. Remote entries whose keys are **not** in the local schema and **not** already set in `process.env` are added to the validated values.
+3. Remote entries whose keys **are** in the local schema are **ignored** — the schema definition always wins.
+4. If the network request fails (timeout, DNS error, etc.), beacon silently falls back to local-only mode.
 
-#### Types
+This gives you a layered config priority:
 
-```ts
-import type {
-  Beacon,
-  BeaconOptions,
-  EnsureOptions,
-  SchemaEntry,
-  FieldDefinition,
-  FieldDefinitionWithSchema,
-  FieldType,
-  FeatureGate,
-  ConfigError,
-  ConfigValidationError,
-} from "@joinremba/beacon";
 ```
+process.env > schema defaults > remote config
+```
+
+Use this to share non-sensitive config (feature flags, service URLs) across deployments without storing everything in every CI/CD pipeline.
+
+---
 
-#### Utilities
+## Related Packages
 
-| Export         | Description                                      |
-|----------------|--------------------------------------------------|
-| `ConfigError`      | Individual config validation error (`key`, `message`, `redacted`). |
-| `ConfigValidationError` | `AggregateError` subclass containing all `ConfigError` instances. |
-| `encryptEnv`       | `(content: string, key: string) => Promise<string>` — AES-256-GCM encrypt. |
-| `decryptEnv`       | `(encrypted: string, key: string) => Promise<string>` — AES-256-GCM decrypt. |
+- [@joinremba/catalog](https://github.com/joinremba/catalog) — Production-ready logging and error event layer on Pino.
+- [@joinremba/gate](https://github.com/joinremba/gate) — API safety layer: validation, responses, idempotency, rate limiting, and API keys.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/beacon",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Validate environment variables, config, secrets, and runtime feature gates before production breaks.",
   "type": "module",
   "main": "./src/index.ts",
@@ -68,10 +68,10 @@
     "bun": ">=1.3.1"
   },
   "dependencies": {
-    "@joinremba/core": "^0.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {
+    "@joinremba/core": "^0.4.0",
     "@types/bun": "latest",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",

package/src/cli-config.ts

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 import type { FeatureGate, SchemaEntry } from "./types";
 import { typeToSchema, type SchemaField } from "./schema";
 
@@ -147,9 +148,10 @@ export async function runCheck(
       const field = entry as { required?: boolean; default?: unknown };
       required = field.required !== false;
       hasDefault = field.default !== undefined;
-    } else {
-      const f = entry as { required?: boolean };
+    } else if ("schema" in entry) {
+      const f = entry as { required?: boolean; schema: z.ZodType<unknown> };
       required = f.required !== false;
+      hasDefault = f.schema.safeParse(undefined).success;
     }
 
     if (raw === undefined || raw === "") {
@@ -164,13 +166,16 @@ export async function runCheck(
       continue;
     }
 
-    const isSecret = isField ? (entry as { secret?: boolean }).secret : false;
+    const isSecret = (entry as { secret?: boolean }).secret ?? false;
     const display = isSecret ? SECRET_CENSOR : raw;
 
     try {
       if (isField) {
         const schema = typeToSchema(entry as SchemaField);
         schema.parse(raw);
+      } else if ("schema" in entry) {
+        const f = entry as { schema: z.ZodType<unknown> };
+        f.schema.parse(raw);
       }
       results.push({
         key,

package/src/cli.ts

@@ -3,6 +3,7 @@
 import { loadConfig, type BeaconConfigFile } from "./cli-config";
 import { generateEnvExample } from "./cli-config";
 import { runCheck } from "./cli-config";
+import { typeToSchema, type SchemaField } from "./schema";
 import { encryptEnv, decryptEnv } from "./encryption";
 import { color, icon, formatCheckResult, formatSummary, suggestKeys } from "./cli-format";
 
@@ -170,9 +171,7 @@ async function handleInit(args: ParsedArgs) {
     : [args.profile];
 
   for (const profile of profilesToGenerate) {
-    const output = profile
-      ? args.output || `.env.example.${profile}`
-      : args.output || ".env.example";
+    const output = profile ? `.env.example.${profile}` : args.output || ".env.example";
     const example = generateEnvExample(config, profile);
     await Bun.write(output, example);
     console.log(` ${icon.pass} Generated ${color.bold(output)}`);
@@ -206,6 +205,29 @@ async function handleCheck(args: ParsedArgs) {
 
   process.stdout.write(formatCheckResult(result.results));
 
+  if (config.features) {
+    const featureEntries = Object.entries(config.features);
+    if (featureEntries.length > 0) {
+      process.stdout.write(`\n ${color.bold("Feature Gates")}\n\n`);
+      for (const [name, gate] of featureEntries) {
+        const envName = `FEATURE_${name
+          .replace(/([a-z])([A-Z])/g, "$1_$2")
+          .replace(/[^a-zA-Z0-9]/g, "_")
+          .toUpperCase()}`;
+        const envVal = process.env[envName];
+        const enabled =
+          envVal !== undefined && envVal !== ""
+            ? envVal === "true" || envVal === "1" || envVal === "yes"
+            : gate.enabled;
+        const icon_ = enabled ? icon.pass : icon.fail;
+        const status = enabled ? color.green("enabled") : color.red("disabled");
+        const desc = gate.description ? ` ${color.dim(`— ${gate.description}`)}` : "";
+        process.stdout.write(`   ${icon_} ${color.bold(name)}: ${status}${desc}\n`);
+      }
+      process.stdout.write("\n");
+    }
+  }
+
   if (result.errors.length > 0) {
     for (const err of result.errors) {
       const suggestions = suggestKeys(
@@ -343,13 +365,24 @@ async function handleDrift(args: ParsedArgs) {
     }
 
     if (isField) {
-      const field = entry as { type?: string; values?: readonly string[] };
-      if (field.type === "enum" && field.values && !field.values.includes(raw)) {
-        driftResults.push({
-          key,
-          expected: `one of: ${field.values.join(" | ")}`,
-          actual: raw,
-        });
+      const schema = typeToSchema(entry as SchemaField);
+      const result = schema.safeParse(raw);
+      if (!result.success) {
+        const field = entry as { type?: string; values?: readonly string[] };
+        if (field.type === "enum" && field.values) {
+          driftResults.push({
+            key,
+            expected: `one of: ${field.values.join(" | ")}`,
+            actual: raw,
+          });
+        } else {
+          const issue = result.error.issues[0];
+          driftResults.push({
+            key,
+            expected: issue?.message ?? "valid value",
+            actual: raw,
+          });
+        }
       }
     }
   }

package/src/index.ts

@@ -14,6 +14,7 @@ import { typeToSchema } from "./schema";
 
 export type {
   BeaconOptions,
+  EnsureOptions,
   FeatureGate,
   FieldDefinition,
   FieldDefinitionWithSchema,
@@ -178,6 +179,13 @@ export function createBeacon(
       return validated[key] as T;
     },
 
+    getAll(): Record<string, unknown> {
+      if (validated === null) {
+        throw new ConfigError("beacon", "Call beacon.ensure() before accessing config values");
+      }
+      return { ...validated };
+    },
+
     get secret(): Record<string, boolean> {
       const map: Record<string, boolean> = {};
       for (const key of secretKeys) {
@@ -186,13 +194,6 @@ export function createBeacon(
       return map;
     },
 
-    getAll(): Record<string, unknown> {
-      if (validated === null) {
-        throw new ConfigError("", "Call beacon.ensure() before accessing config values");
-      }
-      return { ...validated };
-    },
-
     isKilled(feature: string): boolean {
       const envName = `KILL_${feature
         .replace(/([a-z])([A-Z])/g, "$1_$2")

package/src/schema.ts

@@ -27,6 +27,9 @@ export function typeToSchema(field: SchemaField): z.ZodType<unknown> {
     case "boolean":
       base = z
         .string()
+        .refine((v) => ["true", "false", "1", "0", "yes", "no"].includes(v), {
+          message: "Expected one of: true, false, 1, 0, yes, no",
+        })
         .transform((v) => v === "true" || v === "1" || v === "yes")
         .pipe(z.boolean());
       break;

package/src/types.ts

@@ -53,10 +53,8 @@ export interface EnsureOptions {
 export interface Beacon {
   ensure(options?: EnsureOptions): Promise<Beacon>;
   get<T = unknown>(key: string): T;
-  /** Returns all validated entries as a flat key-value record.
-   *  Secrets are included — callers should redact as needed. */
   getAll(): Record<string, unknown>;
   readonly secret: Record<string, boolean>;
-  isEnabled(feature: string): boolean;
   isKilled(feature: string): boolean;
+  isEnabled(feature: string): boolean;
 }