@joinremba/beacon 0.1.0 → 0.3.0

package/README.md

@@ -162,6 +162,7 @@ The default export. Accepts an env schema and optional configuration.
 | `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.                                    |
+| `features` | `Record<string, FeatureGate>`                 | Feature gates for runtime toggles.                          |
 
 **SchemaEntry** can be either:
 
@@ -201,11 +202,12 @@ The default export. Accepts an env schema and optional configuration.
 
 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.                                     |
+| 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.                                     |
+| `isEnabled(feature): boolean` | Checks if a feature gate is enabled. Respects env overrides (`FEATURE_<NAME>`).                              |
 
 ### TypeScript Types
 
@@ -216,6 +218,7 @@ import type {
   SchemaEntry,
   FieldDefinition,
   FieldType,
+  FeatureGate,
   ConfigError,
   ConfigValidationError,
 } from "@joinremba/beacon";
@@ -245,6 +248,10 @@ Used by the CLI for `init` and `check` commands:
     "production": {
       "DB_HOST": { "type": "host", "required": true, "description": "Production DB hostname" }
     }
+  },
+  "features": {
+    "newDashboard": { "enabled": true, "description": "New dashboard UI" },
+    "darkMode": { "enabled": false }
   }
 }
 ```
@@ -320,6 +327,108 @@ const config = createBeacon(
 );
 ```
 
+### Feature Gates
+
+Toggle features on/off without redeploying. Define gates in the `features` option and check them with `isEnabled()`:
+
+```ts
+const config = createBeacon(
+  { DATABASE_URL: { type: "url" } },
+  {
+    features: {
+      newDashboard: { enabled: true },
+      darkMode: { enabled: false },
+      gradualRollout: { enabled: true, rollout: 0.5 },
+    },
+  }
+);
+
+config.isEnabled("newDashboard"); // true
+config.isEnabled("darkMode"); // false
+config.isEnabled("gradualRollout"); // true for ~50% of deployments (deterministic hash)
+```
+
+**Env overrides** — Any feature can be toggled at runtime via `FEATURE_<NAME>`:
+
+```sh
+FEATURE_DARK_MODE=true bun start
+```
+
+CamelCase feature names map to `FEATURE_` prefixed uppercase with underscores (`newDashboard` → `FEATURE_NEW_DASHBOARD`). Accepted truthy values: `true`, `1`, `yes`. Everything else is `false`.
+
+| Option        | Type      | Default | Description                                               |
+| ------------- | --------- | ------- | --------------------------------------------------------- |
+| `enabled`     | `boolean` | `false` | Whether the gate is on by default.                        |
+| `rollout`     | `number`  | —       | Percentage of deployments (0–1). Uses deterministic hash. |
+| `description` | `string`  | —       | Human-readable description.                               |
+
+### Kill-Switch Flags
+
+Force-disable a feature at runtime — overrides any feature gate. Define kill switches in the `killSwitches` option or set `KILL_<NAME>` env vars:
+
+```ts
+const config = createBeacon(
+  { DATABASE_URL: { type: "url" } },
+  {
+    features: { newDashboard: { enabled: true } },
+    killSwitches: { newDashboard: true },
+  }
+);
+
+config.isEnabled("newDashboard"); // false — killed
+config.isKilled("newDashboard"); // true
+```
+
+**Env override** — `KILL_NEW_DASHBOARD=true` overrides the config. Accepted truthy values: `true`, `1`, `yes`.
+
+When a feature is killed, `isEnabled()` returns `false` regardless of the feature gate configuration.
+
+### Encrypted .env (`beacon encrypt` / `beacon decrypt`)
+
+Commit `.env` files safely using AES-256-GCM encryption. Requires an encryption key passed via `--key` or `BEACON_ENCRYPTION_KEY`.
+
+```sh
+# Encrypt .env → .env.encrypted
+BEACON_ENCRYPTION_KEY=your-256-bit-key beacon encrypt
+
+# Decrypt back to plaintext
+BEACON_ENCRYPTION_KEY=your-256-bit-key beacon decrypt
+
+# 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"
+```
+
+### Secret Rotation Checklist (`beacon rotate`)
+
+Prints a step-by-step checklist for rotating secrets (DB credentials, API keys, etc.):
+
+```sh
+beacon rotate
+```
+
+Follows the generate → deploy alongside → update consumers → verify → revoke → audit workflow.
+
+### Config Drift Detection (`beacon drift`)
+
+Detects when your actual environment differs from the schema defined in your config:
+
+```sh
+beacon drift
+beacon drift --profile production
+```
+
+Reports missing required variables, type mismatches, and unexpected enum values.
+
+### Docker/Kubernetes Checks (`beacon docker`)
+
+Validates your environment in container contexts — detects Docker and Kubernetes runtimes, checks common container env vars, and runs a full schema validation:
+
+```sh
+beacon docker
+beacon docker --profile staging
+```
+
 ---
 
 ## Roadmap
@@ -334,15 +443,15 @@ const config = createBeacon(
 - `beacon check` CLI command
 - Coloured CLI output with suggestions
 
-**V1**
+**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
+- Kill-switch flags (`KILL_<NAME>` env vars, `config.isKilled()`)
+- Encrypted `.env` support (`beacon encrypt` / `beacon decrypt`)
+- Secret rotation checklist (`beacon rotate`)
+- CI validation action (`beacon check` in CI workflows)
+- Docker/Kubernetes env checks (`beacon docker`)
+- Config drift detection (`beacon drift`)
 
 **V2**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/beacon",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Validate environment variables, config, secrets, and runtime feature gates before production breaks.",
   "type": "module",
   "main": "./src/index.ts",

package/src/cli-config.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import type { SchemaEntry } from "./types";
+import type { FeatureGate, SchemaEntry } from "./types";
 
 export interface BeaconConfigFile {
   schema: Record<string, SchemaEntry>;
   profile?: string;
   profiles?: Record<string, Record<string, SchemaEntry>>;
+  features?: Record<string, FeatureGate>;
 }
 
 export async function loadConfig(path?: string): Promise<BeaconConfigFile> {
@@ -28,6 +29,10 @@ export async function loadConfig(path?: string): Promise<BeaconConfigFile> {
           config.profiles = parsed.profiles;
         }
 
+        if (parsed.features) {
+          config.features = parsed.features;
+        }
+
         return config;
       } catch (err) {
         if (err instanceof SyntaxError) {

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 { encryptEnv, decryptEnv } from "./encryption";
 import { color, icon, formatCheckResult, formatSummary, suggestKeys } from "./cli-format";
 
 interface ParsedArgs {
@@ -10,6 +11,9 @@ interface ParsedArgs {
   configPath: string;
   output: string;
   profile?: string;
+  key?: string;
+  input?: string;
+  allProfiles: boolean;
   wantsHelp: boolean;
   helpTopic: string;
 }
@@ -18,9 +22,10 @@ function parseArgs(argv: string[]): ParsedArgs {
   const args: ParsedArgs = {
     command: "",
     configPath: "",
-    output: ".env.example",
+    output: "",
     wantsHelp: false,
     helpTopic: "",
+    allProfiles: false,
   };
 
   let i = 0;
@@ -49,6 +54,14 @@ function parseArgs(argv: string[]): ParsedArgs {
     } else if (arg === "--profile") {
       i++;
       args.profile = argv[i] ?? undefined;
+    } else if (arg === "--all-profiles") {
+      args.allProfiles = true;
+    } else if (arg === "--key") {
+      i++;
+      args.key = argv[i] ?? undefined;
+    } else if (arg === "-i" || arg === "--input") {
+      i++;
+      args.input = argv[i] ?? ".env";
     } else if (arg === "--help" || arg === "-h") {
       args.wantsHelp = true;
     } else if (args.command === "" && !arg.startsWith("-") && !args.wantsHelp) {
@@ -71,6 +84,13 @@ async function main() {
   }
 
   if (args.command === "") {
+    if (args.configPath || args.profile || args.key || args.input || args.allProfiles) {
+      console.error(
+        ` ${icon.fail} Missing command. Use ${color.cyan("beacon <command> [options]")}`
+      );
+      console.error(`     Run ${color.cyan("beacon --help")} to see available commands`);
+      process.exit(1);
+    }
     printHelp("");
     return;
   }
@@ -82,6 +102,21 @@ async function main() {
     case "check":
       await handleCheck(args);
       break;
+    case "encrypt":
+      await handleEncrypt(args);
+      break;
+    case "decrypt":
+      await handleDecrypt(args);
+      break;
+    case "rotate":
+      handleRotate(args);
+      return;
+    case "drift":
+      await handleDrift(args);
+      break;
+    case "docker":
+      await handleDockerCheck(args);
+      break;
     default:
       console.error(` ${icon.fail} Unknown command: ${color.bold(args.command)}`);
       printHelp("");
@@ -94,25 +129,61 @@ async function handleInit(args: ParsedArgs) {
 
   try {
     config = await loadConfig(args.configPath || undefined);
-  } catch {
+  } catch (err) {
+    if (args.configPath) {
+      console.error(` ${icon.fail} ${(err as Error).message}`);
+      process.exit(1);
+    }
     config = { schema: {} };
+    console.warn(` ${icon.info} No config file found. Creating ${color.bold(".beaconrc.json")}...`);
+    const template = {
+      schema: {
+        DATABASE_URL: { type: "url", required: true, description: "PostgreSQL connection string" },
+        PORT: { type: "port", default: 3000, description: "HTTP server port" },
+      },
+      profiles: {
+        production: {
+          DB_HOST: { type: "host", required: true, description: "Production DB hostname" },
+        },
+        staging: {
+          DB_HOST: { type: "host", required: true, description: "Staging DB hostname" },
+        },
+      },
+    };
+    await Bun.write(".beaconrc.json", JSON.stringify(template, null, 2) + "\n");
+    console.log(` ${icon.pass} Created ${color.bold(".beaconrc.json")}`);
+    console.log(`     Edit it to define your schema and profiles, then run:`);
+    console.log(
+      `       ${color.cyan("bunx beacon init")}                      ${color.grey("# default profile")}`
+    );
+    console.log(
+      `       ${color.cyan("bunx beacon init --profile production")}  ${color.grey("# production")}`
+    );
+    console.log(
+      `       ${color.cyan("bunx beacon init --all-profiles")}        ${color.grey("# all profiles")}`
+    );
+    process.exit(0);
   }
 
-  const profile = args.profile;
-  const example = generateEnvExample(config, profile);
-  await Bun.write(args.output, example);
-  console.log(` ${icon.pass} Generated ${color.bold(args.output)}`);
-  if (profile) {
-    console.log(`     Profile: ${color.cyan(profile)}`);
+  const profilesToGenerate = args.allProfiles
+    ? [undefined, ...Object.keys(config.profiles ?? {})]
+    : [args.profile];
+
+  for (const profile of profilesToGenerate) {
+    const output = profile
+      ? args.output || `.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)}`);
+    if (profile) {
+      console.log(`     Profile: ${color.cyan(profile)}`);
+    }
   }
 
-  const count = Object.keys(
-    profile && config.profiles?.[profile]
-      ? { ...config.schema, ...config.profiles[profile] }
-      : config.schema
-  ).length;
-  if (count > 0) {
-    console.log(`     ${count} variable(s) documented`);
+  const schemaKeys = Object.keys(config.schema).length;
+  if (schemaKeys > 0) {
+    console.log(`     ${schemaKeys} variable(s) documented`);
   }
   process.exit(0);
 }
@@ -159,6 +230,204 @@ async function handleCheck(args: ParsedArgs) {
   process.exit(0);
 }
 
+async function handleEncrypt(args: ParsedArgs) {
+  const encryptionKey = args.key ?? process.env.BEACON_ENCRYPTION_KEY;
+  if (!encryptionKey) {
+    console.error(
+      ` ${icon.fail} Encryption key required. Pass --key <key> or set BEACON_ENCRYPTION_KEY`
+    );
+    process.exit(1);
+  }
+
+  const inputPath = args.input ?? ".env";
+  const file = Bun.file(inputPath);
+  const exists = await file.exists();
+  if (!exists) {
+    console.error(` ${icon.fail} Input file not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  const content = await file.text();
+  const encrypted = await encryptEnv(content, encryptionKey);
+  const outputPath = args.output;
+  await Bun.write(outputPath, encrypted);
+  console.log(` ${icon.pass} Encrypted ${color.bold(inputPath)} → ${color.bold(outputPath)}`);
+  process.exit(0);
+}
+
+async function handleDecrypt(args: ParsedArgs) {
+  const encryptionKey = args.key ?? process.env.BEACON_ENCRYPTION_KEY;
+  if (!encryptionKey) {
+    console.error(
+      ` ${icon.fail} Encryption key required. Pass --key <key> or set BEACON_ENCRYPTION_KEY`
+    );
+    process.exit(1);
+  }
+
+  const inputPath = args.input ?? ".env.encrypted";
+  const file = Bun.file(inputPath);
+  const exists = await file.exists();
+  if (!exists) {
+    console.error(` ${icon.fail} Encrypted file not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  const encryptedBase64 = (await file.text()).trim();
+  const decrypted = await decryptEnv(encryptedBase64, encryptionKey);
+  const outputPath = args.output;
+  await Bun.write(outputPath, decrypted);
+  console.log(` ${icon.pass} Decrypted ${color.bold(inputPath)} → ${color.bold(outputPath)}`);
+  process.exit(0);
+}
+
+function handleRotate(_args: ParsedArgs) {
+  console.log(`
+ ${color.bold("Secret Rotation Checklist")}
+
+Follow these steps to rotate a secret safely:
+
+ ${color.bold("1.")} Generate a new secret value
+     Use: openssl rand -base64 32
+
+ ${color.bold("2.")} Deploy the new secret alongside the old one
+     Add the new value to your env/secret store (e.g. DATABASE_URL_NEW)
+     Your app should accept both old and new values during the transition
+
+ ${color.bold("3.")} Update all consumers to use the new secret
+     Deploy config changes pointing to the new secret
+
+ ${color.bold("4.")} Verify everything works
+     Run: ${color.cyan("bunx beacon check")}
+     Check logs, metrics, and error rates
+
+ ${color.bold("5.")} Revoke the old secret
+     Remove the old value from your env/secret store
+     Rotate any credentials in external services
+
+ ${color.bold("6.")} Audit
+     Confirm no services still reference the old secret
+     Update docs and secrets inventory
+
+ ${color.dim("Pro tip: Use beacon encrypt to store secrets safely in git.")}
+ ${color.dim("         Set BEACON_ENCRYPTION_KEY in your deployment env.")}
+`);
+}
+
+async function handleDrift(args: ParsedArgs) {
+  let config: BeaconConfigFile;
+  try {
+    config = await loadConfig(args.configPath || undefined);
+  } catch (err) {
+    console.error(` ${icon.fail} ${(err as Error).message}`);
+    process.exit(1);
+  }
+
+  const profile = args.profile;
+  const mergedSchema = { ...config.schema };
+  if (profile && config.profiles?.[profile]) {
+    Object.assign(mergedSchema, config.profiles[profile]);
+  }
+
+  const driftResults: Array<{ key: string; expected: string; actual: string }> = [];
+
+  for (const [key, entry] of Object.entries(mergedSchema)) {
+    const raw = process.env[key];
+    const isField = "type" in entry;
+    const required = isField ? (entry as { required?: boolean }).required !== false : true;
+
+    if (raw === undefined || raw === "") {
+      if (required) {
+        driftResults.push({ key, expected: "set", actual: "not set" });
+      }
+      continue;
+    }
+
+    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,
+        });
+      }
+    }
+  }
+
+  if (driftResults.length === 0) {
+    console.log(` ${icon.pass} ${color.bold("No config drift detected")}`);
+    process.exit(0);
+  }
+
+  console.log(` ${icon.fail} ${color.bold("Config drift detected:")}\n`);
+  for (const d of driftResults) {
+    console.log(`   ${color.yellow("⚠")} ${color.bold(d.key)}`);
+    console.log(`       Expected: ${color.cyan(d.expected)}`);
+    console.log(`       Actual:   ${color.red(d.actual)}`);
+    console.log();
+  }
+  process.exit(1);
+}
+
+async function handleDockerCheck(args: ParsedArgs) {
+  const isDocker = await Bun.file("/.dockerenv")
+    .exists()
+    .catch(() => false);
+  const isK8s = process.env.KUBERNETES_SERVICE_HOST !== undefined;
+
+  console.log(` ${icon.info} ${color.bold("Environment Detection")}\n`);
+
+  if (isDocker) {
+    console.log(`   ${icon.pass} Running inside Docker container`);
+  } else {
+    console.log(`   ${color.dim("○")} Not detected as Docker`);
+  }
+
+  if (isK8s) {
+    console.log(`   ${icon.pass} Running inside Kubernetes pod`);
+    console.log(
+      `       KUBERNETES_SERVICE_HOST=${color.cyan(process.env.KUBERNETES_SERVICE_HOST ?? "")}`
+    );
+  } else {
+    console.log(`   ${color.dim("○")} Not detected as Kubernetes`);
+  }
+
+  console.log();
+
+  const dockerVars = ["DOCKER_HOST", "CONTAINER_NAME", "COMPOSE_PROJECT_NAME"];
+  const k8sVars = ["KUBERNETES_SERVICE_HOST", "KUBERNETES_SERVICE_PORT"];
+
+  if (isDocker || isK8s) {
+    console.log(` ${icon.info} ${color.bold("Container Env Vars Found")}\n`);
+    const relevant = [...(isDocker ? dockerVars : []), ...(isK8s ? k8sVars : [])];
+    for (const v of relevant) {
+      if (process.env[v]) {
+        console.log(`   ${color.green("✓")} ${v}=${color.dim(process.env[v] ?? "")}`);
+      }
+    }
+    console.log();
+  }
+
+  let config: BeaconConfigFile | undefined;
+  try {
+    config = await loadConfig(args.configPath || undefined);
+  } catch {
+    // no config file, just show env info
+  }
+
+  if (config) {
+    console.log(` ${icon.info} ${color.bold("Running beacon check against schema")}\n`);
+    const result = await runCheck(config, args.profile);
+    process.stdout.write(formatCheckResult(result.results));
+    const passed = result.results.filter((r) => r.status === "ok").length;
+    const failed = result.results.filter((r) => r.status !== "ok").length;
+    process.stdout.write(formatSummary(passed, failed));
+    if (failed > 0) process.exit(1);
+  }
+
+  process.exit(0);
+}
+
 function printHelp(command: string) {
   if (command === "init") {
     console.log(`
@@ -172,19 +441,130 @@ ${color.bold("DESCRIPTION")}
 
 ${color.bold("OPTIONS")}
   -c, --config <path>  Path to config file
-                       ${color.dim("(default: .beaconrc.json or beacon.config.json)")}
+                        ${color.dim("(default: .beaconrc.json or beacon.config.json)")}
   -o, --output <path>  Output file for init
-                       ${color.dim("(default: .env.example)")}
-  --profile <name>     Profile to merge (staging, production, etc.)
+                        ${color.dim("(default: .env.example or .env.example.<profile>)")}
+  --profile <name>     Generate for a specific profile
+  --all-profiles       Generate .env.example for every profile
 
 ${color.bold("EXAMPLES")}
   beacon init                              ${color.grey("# generate .env.example")}
-  beacon init --profile production         ${color.grey("# merge production profile")}
+  beacon init --profile production         ${color.grey("# generate .env.example.production")}
+  beacon init --all-profiles               ${color.grey("# generate for all profiles")}
   beacon init -c ./config/beacon.json      ${color.grey("# custom config path")}
 `);
     return;
   }
 
+  if (command === "rotate") {
+    console.log(`
+${color.bold("USAGE")}
+  beacon rotate
+
+${color.bold("DESCRIPTION")}
+  Print a step-by-step secret rotation checklist.
+  Follow it to rotate any secret (DB credentials, API keys, etc.).
+
+${color.bold("EXAMPLES")}
+  beacon rotate
+`);
+    return;
+  }
+
+  if (command === "drift") {
+    console.log(`
+${color.bold("USAGE")}
+  beacon drift [options]
+
+${color.bold("DESCRIPTION")}
+  Detect config drift — compares your actual environment against
+  the schema defined in your beacon config file.
+  Reports missing variables, type mismatches, and unexpected values.
+
+${color.bold("OPTIONS")}
+  -c, --config <path>  Path to config file
+                        ${color.dim("(default: .beaconrc.json or beacon.config.json)")}
+  --profile <name>     Profile to merge (staging, production, etc.)
+
+${color.bold("EXAMPLES")}
+  beacon drift
+  beacon drift --profile production
+`);
+    return;
+  }
+
+  if (command === "docker") {
+    console.log(`
+${color.bold("USAGE")}
+  beacon docker [options]
+
+${color.bold("DESCRIPTION")}
+  Validate the environment in Docker and Kubernetes contexts.
+  Detects the container runtime, checks common container env vars,
+  and runs a full beacon check against your schema.
+
+${color.bold("OPTIONS")}
+  -c, --config <path>  Path to config file
+                        ${color.dim("(default: .beaconrc.json or beacon.config.json)")}
+  --profile <name>     Profile to merge
+
+${color.bold("EXAMPLES")}
+  beacon docker
+  beacon docker --profile staging
+`);
+    return;
+  }
+
+  if (command === "encrypt") {
+    console.log(`
+${color.bold("USAGE")}
+  beacon encrypt [options]
+
+${color.bold("DESCRIPTION")}
+  Encrypt a .env file so secrets can be committed safely.
+  Requires a 256-bit encryption key (passed via --key or BEACON_ENCRYPTION_KEY).
+
+${color.bold("OPTIONS")}
+  -i, --input <path>   Input .env file
+                        ${color.dim("(default: .env)")}
+  -o, --output <path>  Output encrypted file
+                        ${color.dim("(default: .env.encrypted)")}
+  --key <key>          Encryption key
+                        ${color.dim("(or set BEACON_ENCRYPTION_KEY)")}
+
+${color.bold("EXAMPLES")}
+  beacon encrypt                                           ${color.grey("# encrypt .env → .env.encrypted")}
+  beacon encrypt -i .env.prod -o .env.prod.encrypted       ${color.grey("# custom paths")}
+  BEACON_ENCRYPTION_KEY=... beacon encrypt                 ${color.grey("# key from env")}
+`);
+    return;
+  }
+
+  if (command === "decrypt") {
+    console.log(`
+${color.bold("USAGE")}
+  beacon decrypt [options]
+
+${color.bold("DESCRIPTION")}
+  Decrypt a .env.encrypted file back to plaintext.
+  Requires the same key used during encryption.
+
+${color.bold("OPTIONS")}
+  -i, --input <path>   Input encrypted file
+                        ${color.dim("(default: .env.encrypted)")}
+  -o, --output <path>  Output .env file
+                        ${color.dim("(default: .env)")}
+  --key <key>          Encryption key
+                        ${color.dim("(or set BEACON_ENCRYPTION_KEY)")}
+
+${color.bold("EXAMPLES")}
+  beacon decrypt                                           ${color.grey("# decrypt .env.encrypted → .env")}
+  beacon decrypt -i .env.prod.encrypted -o .env.prod       ${color.grey("# custom paths")}
+  BEACON_ENCRYPTION_KEY=... beacon decrypt                 ${color.grey("# key from env")}
+`);
+    return;
+  }
+
   if (command === "check") {
     console.log(`
 ${color.bold("USAGE")}
@@ -218,9 +598,14 @@ ${color.bold("USAGE")}
   beacon <command> [options]
 
 ${color.bold("COMMANDS")}
-  init   ${color.dim("Generate .env.example from your config")}
-  check  ${color.dim("Validate current environment against your schema")}
-  help   ${color.dim("Show help for a specific command")}
+  init     ${color.dim("Generate .env.example from your config")}
+  check    ${color.dim("Validate current environment against your schema")}
+  encrypt  ${color.dim("Encrypt .env file for safe committing")}
+  decrypt  ${color.dim("Decrypt .env.encrypted back to plaintext")}
+  rotate   ${color.dim("Print secret rotation checklist")}
+  drift    ${color.dim("Detect config drift between schema and env")}
+  docker   ${color.dim("Validate env in Docker/Kubernetes contexts")}
+  help     ${color.dim("Show help for a specific command")}
 
 ${color.bold("OPTIONS")}
   -c, --config <path>  Path to config file (default: .beaconrc.json or beacon.config.json)

package/src/encryption.test.ts

@@ -0,0 +1,24 @@
+import { test, expect } from "bun:test";
+import { encryptEnv, decryptEnv } from "./encryption";
+
+test("encrypts and decrypts env content", async () => {
+  const key = "test-encryption-key-32bytes!";
+  const envContent = `DATABASE_URL=postgres://localhost/mydb
+API_KEY=supersecret123
+PORT=3000`;
+
+  const encrypted = await encryptEnv(envContent, key);
+  expect(typeof encrypted).toBe("string");
+  expect(encrypted.length).toBeGreaterThan(0);
+
+  const decrypted = await decryptEnv(encrypted, key);
+  expect(decrypted).toBe(envContent);
+});
+
+test("rejects wrong key", async () => {
+  const key = "correct-key-32bytes!!!!!";
+  const envContent = "SECRET=value";
+  const encrypted = await encryptEnv(envContent, key);
+  const result = await decryptEnv(encrypted, "wrong-key-32bytes!!!!!!").catch(() => "error");
+  expect(result).toBe("error");
+});

package/src/encryption.ts

@@ -0,0 +1,59 @@
+const ALGORITHM = "AES-GCM";
+const IV_LENGTH = 12;
+const TAG_LENGTH = 128;
+
+function keyToBuf(key: Uint8Array): ArrayBuffer {
+  const buf = new ArrayBuffer(key.byteLength);
+  new Uint8Array(buf).set(key);
+  return buf;
+}
+
+async function deriveKey(password: string): Promise<CryptoKey> {
+  const encoded = new TextEncoder().encode(password);
+  const raw =
+    encoded.length >= 32
+      ? encoded.slice(0, 32)
+      : (() => {
+          const p = new Uint8Array(32);
+          p.set(encoded);
+          return p;
+        })();
+  return crypto.subtle.importKey("raw", keyToBuf(raw), { name: ALGORITHM }, false, [
+    "encrypt",
+    "decrypt",
+  ]);
+}
+
+export async function encryptEnv(envContent: string, key: string): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const cryptoKey = await deriveKey(key);
+  const data = new TextEncoder().encode(envContent);
+
+  const encrypted = await crypto.subtle.encrypt(
+    { name: ALGORITHM, iv, tagLength: TAG_LENGTH },
+    cryptoKey,
+    data
+  );
+
+  const combined = new Uint8Array(IV_LENGTH + encrypted.byteLength);
+  combined.set(iv, 0);
+  combined.set(new Uint8Array(encrypted), IV_LENGTH);
+
+  return Buffer.from(combined).toString("base64");
+}
+
+export async function decryptEnv(encryptedBase64: string, key: string): Promise<string> {
+  const combined = Buffer.from(encryptedBase64, "base64");
+  const iv = combined.slice(0, IV_LENGTH);
+  const data = combined.slice(IV_LENGTH);
+
+  const cryptoKey = await deriveKey(key);
+
+  const decrypted = await crypto.subtle.decrypt(
+    { name: ALGORITHM, iv, tagLength: TAG_LENGTH },
+    cryptoKey,
+    data
+  );
+
+  return new TextDecoder().decode(decrypted);
+}

package/src/index.test.ts

@@ -176,3 +176,89 @@ test("tracks secret keys", () => {
 
   expect(config.secret).toEqual({ API_KEY: true });
 });
+
+test("isEnabled returns false for undefined feature", () => {
+  const config = createBeacon({ PORT: { type: "port", default: 3000 } });
+  expect(config.isEnabled("nonexistent")).toBe(false);
+});
+
+test("isEnabled returns true for enabled feature", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { features: { newDashboard: { enabled: true } } }
+  );
+  expect(config.isEnabled("newDashboard")).toBe(true);
+});
+
+test("isEnabled returns false for disabled feature", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { features: { darkMode: { enabled: false } } }
+  );
+  expect(config.isEnabled("darkMode")).toBe(false);
+});
+
+test("isEnabled respects env override", () => {
+  const prev = process.env.FEATURE_NEW_DASHBOARD;
+  try {
+    process.env.FEATURE_NEW_DASHBOARD = "false";
+    const config = createBeacon(
+      { PORT: { type: "port", default: 3000 } },
+      { features: { newDashboard: { enabled: true } } }
+    );
+    expect(config.isEnabled("newDashboard")).toBe(false);
+  } finally {
+    if (prev === undefined) {
+      delete process.env.FEATURE_NEW_DASHBOARD;
+    } else {
+      process.env.FEATURE_NEW_DASHBOARD = prev;
+    }
+  }
+});
+
+test("isEnabled uses rollout when enabled is true", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { features: { gradual: { enabled: true, rollout: 1 } } }
+  );
+  expect(config.isEnabled("gradual")).toBe(true);
+});
+
+test("isKilled returns false by default", () => {
+  const config = createBeacon({ PORT: { type: "port", default: 3000 } });
+  expect(config.isKilled("newDashboard")).toBe(false);
+});
+
+test("isKilled returns true when set in options", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { killSwitches: { newDashboard: true } }
+  );
+  expect(config.isKilled("newDashboard")).toBe(true);
+});
+
+test("isKilled respects KILL_ env override", () => {
+  const prev = process.env.KILL_NEW_DASHBOARD;
+  try {
+    process.env.KILL_NEW_DASHBOARD = "true";
+    const config = createBeacon(
+      { PORT: { type: "port", default: 3000 } },
+      { killSwitches: { newDashboard: false } }
+    );
+    expect(config.isKilled("newDashboard")).toBe(true);
+  } finally {
+    if (prev === undefined) delete process.env.KILL_NEW_DASHBOARD;
+    else process.env.KILL_NEW_DASHBOARD = prev;
+  }
+});
+
+test("isEnabled returns false when feature is killed", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    {
+      features: { newDashboard: { enabled: true } },
+      killSwitches: { newDashboard: true },
+    }
+  );
+  expect(config.isEnabled("newDashboard")).toBe(false);
+});

package/src/index.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type {
   Beacon as BeaconInterface,
   BeaconOptions,
+  FeatureGate,
   FieldDefinition,
   FieldDefinitionWithSchema,
   SchemaEntry,
@@ -9,7 +10,14 @@ import type {
 } from "./types";
 import { ConfigError, ConfigValidationError } from "./errors";
 
-export type { BeaconOptions, FieldDefinition, FieldDefinitionWithSchema, SchemaEntry, FieldType };
+export type {
+  BeaconOptions,
+  FeatureGate,
+  FieldDefinition,
+  FieldDefinitionWithSchema,
+  SchemaEntry,
+  FieldType,
+};
 export { ConfigError, ConfigValidationError };
 export type { BeaconInterface as Beacon };
 
@@ -93,6 +101,22 @@ const resolveEntry = (
 
 const SECRET_CENSOR = "[REDACTED]";
 
+const featureEnvName = (name: string): string =>
+  `FEATURE_${name
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/[^a-zA-Z0-9]/g, "_")
+    .toUpperCase()}`;
+
+const parseEnvBoolean = (val: string): boolean => val === "true" || val === "1" || val === "yes";
+
+const featureRollup = (name: string): number => {
+  let hash = 5381;
+  for (let i = 0; i < name.length; i++) {
+    hash = ((hash << 5) + hash + name.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash % 10000) / 10000;
+};
+
 export function createBeacon(
   schema: Record<string, SchemaEntry>,
   options?: BeaconOptions
@@ -111,6 +135,8 @@ export function createBeacon(
   const secretKeys = new Set(resolved.filter((e) => e.secret).map((e) => e.key));
 
   let validated: Record<string, unknown> | null = null;
+  const features: Record<string, FeatureGate> = options?.features ?? {};
+  const killSwitches: Record<string, boolean> = options?.killSwitches ?? {};
 
   const beacon: BeaconInterface = {
     ensure(): BeaconInterface {
@@ -189,6 +215,34 @@ export function createBeacon(
       }
       return map;
     },
+
+    isKilled(feature: string): boolean {
+      const envName = `KILL_${feature
+        .replace(/([a-z])([A-Z])/g, "$1_$2")
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .toUpperCase()}`;
+      const envVal = process.env[envName];
+      if (envVal !== undefined && envVal !== "") {
+        return parseEnvBoolean(envVal);
+      }
+      return killSwitches[feature] ?? false;
+    },
+
+    isEnabled(feature: string): boolean {
+      if (this.isKilled(feature)) return false;
+      const envName = featureEnvName(feature);
+      const envVal = process.env[envName];
+      if (envVal !== undefined && envVal !== "") {
+        return parseEnvBoolean(envVal);
+      }
+      const gate = features[feature];
+      if (!gate) return false;
+      if (!gate.enabled) return false;
+      if (gate.rollout !== undefined) {
+        return featureRollup(feature) < gate.rollout;
+      }
+      return true;
+    },
   };
 
   return beacon;

package/src/types.ts

@@ -29,13 +29,23 @@ export interface FieldDefinitionWithSchema {
 
 export type SchemaEntry = FieldDefinition | FieldDefinitionWithSchema;
 
+export interface FeatureGate {
+  enabled: boolean;
+  rollout?: number;
+  description?: string;
+}
+
 export interface BeaconOptions {
   profile?: string;
   profiles?: Record<string, Record<string, SchemaEntry>>;
+  features?: Record<string, FeatureGate>;
+  killSwitches?: Record<string, boolean>;
 }
 
 export interface Beacon {
   ensure(): Beacon;
   get<T = unknown>(key: string): T;
   readonly secret: Record<string, boolean>;
+  isEnabled(feature: string): boolean;
+  isKilled(feature: string): boolean;
 }