@joinremba/beacon 0.1.0 → 0.4.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.4.0",
   "description": "Validate environment variables, config, secrets, and runtime feature gates before production breaks.",
   "type": "module",
   "main": "./src/index.ts",
@@ -68,6 +68,7 @@
     "bun": ">=1.3.1"
   },
   "dependencies": {
+    "@joinremba/core": "^0.4.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/src/cli-config.ts

@@ -1,10 +1,11 @@
-import { z } from "zod";
-import type { SchemaEntry } from "./types";
+import type { FeatureGate, SchemaEntry } from "./types";
+import { typeToSchema, type SchemaField } from "./schema";
 
 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) {
@@ -114,49 +119,7 @@ export function generateEnvExample(config: BeaconConfigFile, activeProfile?: str
   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;
-};
+const SECRET_CENSOR = "[REDACTED]";
 
 export async function runCheck(
   config: BeaconConfigFile,
@@ -201,19 +164,22 @@ export async function runCheck(
       continue;
     }
 
+    const isSecret = isField ? (entry as { secret?: boolean }).secret : false;
+    const display = isSecret ? SECRET_CENSOR : raw;
+
     try {
       if (isField) {
-        const schema = typeToSchema(entry as unknown as Record<string, unknown>);
+        const schema = typeToSchema(entry as SchemaField);
         schema.parse(raw);
       }
       results.push({
         key,
         status: "ok",
-        message: `Set (${raw.length > 25 ? raw.substring(0, 25) + "..." : raw})`,
+        message: `Set (${display.length > 25 ? display.substring(0, 25) + "..." : display})`,
       });
     } catch {
-      results.push({ key, status: "invalid", message: `Invalid: "${raw}"` });
-      errors.push({ key, message: `Invalid value: ${raw}` });
+      results.push({ key, status: "invalid", message: `Invalid: "${display}"` });
+      errors.push({ key, message: `Invalid value: ${display}` });
     }
   }
 

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, describe } from "bun:test";
-import { generateEnvExample } from "./cli-config";
+import { generateEnvExample, runCheck } from "./cli-config";
 import type { BeaconConfigFile } from "./cli-config";
 
 describe("generateEnvExample", () => {
@@ -51,3 +51,53 @@ describe("generateEnvExample", () => {
     expect(result).toContain("Secret: yes");
   });
 });
+
+describe("runCheck", () => {
+  test("returns ok for present and valid env vars", async () => {
+    const prev = process.env.TEST_DB_URL;
+    process.env.TEST_DB_URL = "https://example.com/db";
+    try {
+      const config: BeaconConfigFile = {
+        schema: {
+          TEST_DB_URL: { type: "url", required: true },
+        },
+      };
+      const result = await runCheck(config);
+      expect(result.results).toHaveLength(1);
+      expect(result.results[0]?.status).toBe("ok");
+    } finally {
+      if (prev === undefined) delete process.env.TEST_DB_URL;
+      else process.env.TEST_DB_URL = prev;
+    }
+  });
+
+  test("returns missing for absent required var", async () => {
+    delete process.env.TEST_MISSING;
+    const config: BeaconConfigFile = {
+      schema: {
+        TEST_MISSING: { type: "string", required: true },
+      },
+    };
+    const result = await runCheck(config);
+    expect(result.results[0]?.status).toBe("missing");
+  });
+
+  test("redacts secret values on invalid", async () => {
+    const prev = process.env.TEST_SECRET;
+    process.env.TEST_SECRET = "my-secret-value-that-should-not-leak";
+    try {
+      const config: BeaconConfigFile = {
+        schema: {
+          TEST_SECRET: { type: "integer", secret: true },
+        },
+      };
+      const result = await runCheck(config);
+      expect(result.results[0]?.status).toBe("invalid");
+      expect(result.results[0]?.message).not.toContain("my-secret-value");
+      expect(result.errors[0]?.message).not.toContain("my-secret-value");
+    } finally {
+      if (prev === undefined) delete process.env.TEST_SECRET;
+      else process.env.TEST_SECRET = prev;
+    }
+  });
+});