@joinremba/beacon 0.1.0

package/src/cli-format.ts

@@ -0,0 +1,100 @@
+const ESC = "\x1b";
+
+export const color = {
+  green: (s: string) => `${ESC}[32m${s}${ESC}[39m`,
+  red: (s: string) => `${ESC}[31m${s}${ESC}[39m`,
+  yellow: (s: string) => `${ESC}[33m${s}${ESC}[39m`,
+  dim: (s: string) => `${ESC}[2m${s}${ESC}[22m`,
+  bold: (s: string) => `${ESC}[1m${s}${ESC}[22m`,
+  cyan: (s: string) => `${ESC}[36m${s}${ESC}[39m`,
+  grey: (s: string) => `${ESC}[90m${s}${ESC}[39m`,
+};
+
+export const icon = {
+  pass: color.green("\u2713"),
+  fail: color.red("\u2717"),
+  warn: color.yellow("!"),
+  info: color.cyan("i"),
+};
+
+export function formatCheckResult(
+  results: Array<{ key: string; status: "ok" | "missing" | "invalid"; message: string }>
+): string {
+  if (results.length === 0) return color.dim("  No variables defined in schema.\n");
+
+  const keyWidth = Math.min(Math.max(...results.map((r) => r.key.length), 4), 50);
+
+  const lines: string[] = [];
+  lines.push(
+    `  ${color.dim("KEY".padEnd(keyWidth))}  ${color.dim("STATUS")}  ${color.dim("VALUE")}`
+  );
+  lines.push(
+    `  ${color.dim("\u2500".repeat(keyWidth))}  ${color.dim("\u2500".repeat(6))}  ${color.dim("\u2500".repeat(20))}`
+  );
+
+  for (const item of results) {
+    const key = item.key.padEnd(keyWidth);
+
+    let statusText: string;
+    let valueText: string;
+
+    switch (item.status) {
+      case "ok":
+        statusText = color.green("pass");
+        valueText = color.dim(item.message);
+        break;
+      case "missing":
+        statusText = color.red("MISSING");
+        valueText = item.message;
+        break;
+      case "invalid":
+        statusText = color.yellow("INVALID");
+        valueText = item.message;
+        break;
+    }
+
+    lines.push(`  ${key}  ${statusText}  ${valueText}`);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+export function formatSummary(passed: number, failed: number): string {
+  if (failed === 0) {
+    return color.green(`\u2713 All ${passed} variable(s) pass.\n`);
+  }
+  const parts: string[] = [];
+  if (failed > 0) parts.push(color.red(`${failed} issue(s)`));
+  if (passed > 0) parts.push(color.green(`${passed} pass`));
+  return `  ${parts.join(", ")}\n`;
+}
+
+export function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = [];
+  for (let i = 0; i <= m; i++) {
+    dp.push([]);
+    for (let j = 0; j <= n; j++) {
+      dp[i]!.push(0);
+    }
+  }
+  for (let i = 0; i <= m; i++) dp[i]![0] = i;
+  for (let j = 0; j <= n; j++) dp[0]![j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(dp[i - 1]![j]! + 1, dp[i]![j - 1]! + 1, dp[i - 1]![j - 1]! + cost);
+    }
+  }
+  return dp[m]![n]!;
+}
+
+export function suggestKeys(missingKey: string, allKeys: string[], maxSuggestions = 3): string[] {
+  const scored = allKeys
+    .map((k) => ({ key: k, score: levenshtein(missingKey.toLowerCase(), k.toLowerCase()) }))
+    .filter((s) => s.score <= 4 && s.score > 0)
+    .sort((a, b) => a.score - b.score);
+
+  return scored.slice(0, maxSuggestions).map((s) => s.key);
+}

package/src/cli.test.ts

@@ -0,0 +1,53 @@
+import { expect, test, describe } from "bun:test";
+import { generateEnvExample } from "./cli-config";
+import type { BeaconConfigFile } from "./cli-config";
+
+describe("generateEnvExample", () => {
+  test("generates basic env example", () => {
+    const config: BeaconConfigFile = {
+      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",
+        },
+      },
+    };
+
+    const result = generateEnvExample(config);
+    expect(result).toContain("DATABASE_URL");
+    expect(result).toContain("PostgreSQL connection string");
+    expect(result).toContain("PORT=3000");
+    expect(result).toContain("development | production");
+  });
+
+  test("includes profile override when activeProfile is set", () => {
+    const config: BeaconConfigFile = {
+      schema: {
+        DB_HOST: { type: "string", default: "localhost" },
+      },
+      profiles: {
+        production: {
+          DB_HOST: { type: "host", required: true, description: "Production DB host" },
+        },
+      },
+    };
+
+    const result = generateEnvExample(config, "production");
+    expect(result).toContain("Profile: production");
+    expect(result).toContain("Production DB host");
+  });
+
+  test("marks secret vars", () => {
+    const config: BeaconConfigFile = {
+      schema: {
+        API_KEY: { type: "string", secret: true, description: "API secret key" },
+      },
+    };
+
+    const result = generateEnvExample(config);
+    expect(result).toContain("Secret: yes");
+  });
+});

package/src/cli.ts

@@ -0,0 +1,243 @@
+#!/usr/bin/env bun
+
+import { loadConfig, type BeaconConfigFile } from "./cli-config";
+import { generateEnvExample } from "./cli-config";
+import { runCheck } from "./cli-config";
+import { color, icon, formatCheckResult, formatSummary, suggestKeys } from "./cli-format";
+
+interface ParsedArgs {
+  command: string;
+  configPath: string;
+  output: string;
+  profile?: string;
+  wantsHelp: boolean;
+  helpTopic: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args: ParsedArgs = {
+    command: "",
+    configPath: "",
+    output: ".env.example",
+    wantsHelp: false,
+    helpTopic: "",
+  };
+
+  let i = 0;
+
+  const first = argv[i];
+  if (first !== undefined && !first.startsWith("-")) {
+    const val = first;
+    if (val === "help") {
+      args.command = "help";
+      i++;
+      args.helpTopic = argv[i] ?? "";
+      return args;
+    }
+    args.command = val;
+    i++;
+  }
+
+  while (i < argv.length) {
+    const arg = argv[i] as string;
+    if (arg === "-c" || arg === "--config") {
+      i++;
+      args.configPath = argv[i] ?? "";
+    } else if (arg === "-o" || arg === "--output") {
+      i++;
+      args.output = argv[i] ?? ".env.example";
+    } else if (arg === "--profile") {
+      i++;
+      args.profile = argv[i] ?? undefined;
+    } else if (arg === "--help" || arg === "-h") {
+      args.wantsHelp = true;
+    } else if (args.command === "" && !arg.startsWith("-") && !args.wantsHelp) {
+      args.command = arg;
+    }
+    i++;
+  }
+
+  return args;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv);
+
+  if (args.wantsHelp || args.command === "help") {
+    const topic = args.command === "help" ? args.helpTopic : args.command;
+    printHelp(topic);
+    return;
+  }
+
+  if (args.command === "") {
+    printHelp("");
+    return;
+  }
+
+  switch (args.command) {
+    case "init":
+      await handleInit(args);
+      break;
+    case "check":
+      await handleCheck(args);
+      break;
+    default:
+      console.error(` ${icon.fail} Unknown command: ${color.bold(args.command)}`);
+      printHelp("");
+      process.exit(1);
+  }
+}
+
+async function handleInit(args: ParsedArgs) {
+  let config: BeaconConfigFile;
+
+  try {
+    config = await loadConfig(args.configPath || undefined);
+  } catch {
+    config = { schema: {} };
+  }
+
+  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 count = Object.keys(
+    profile && config.profiles?.[profile]
+      ? { ...config.schema, ...config.profiles[profile] }
+      : config.schema
+  ).length;
+  if (count > 0) {
+    console.log(`     ${count} variable(s) documented`);
+  }
+  process.exit(0);
+}
+
+async function handleCheck(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;
+  if (profile) {
+    console.log(`   ${icon.info} Profile: ${color.cyan(profile)}\n`);
+  }
+
+  const result = await runCheck(config, profile);
+
+  process.stdout.write(formatCheckResult(result.results));
+
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      const suggestions = suggestKeys(
+        err.key,
+        Object.keys(config.schema).filter((k) => k !== err.key)
+      );
+      if (suggestions.length > 0) {
+        process.stdout.write(
+          `     ${color.dim(`Did you mean ${suggestions.map((s) => color.cyan(s)).join(" or ")}?`)}\n`
+        );
+      }
+    }
+  }
+
+  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(`
+${color.bold("USAGE")}
+  beacon init [options]
+
+${color.bold("DESCRIPTION")}
+  Generate a .env.example file from your beacon config file.
+  Reads your schema and creates a documented template with
+  types, defaults, and descriptions for every variable.
+
+${color.bold("OPTIONS")}
+  -c, --config <path>  Path to config file
+                       ${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.bold("EXAMPLES")}
+  beacon init                              ${color.grey("# generate .env.example")}
+  beacon init --profile production         ${color.grey("# merge production profile")}
+  beacon init -c ./config/beacon.json      ${color.grey("# custom config path")}
+`);
+    return;
+  }
+
+  if (command === "check") {
+    console.log(`
+${color.bold("USAGE")}
+  beacon check [options]
+
+${color.bold("DESCRIPTION")}
+  Validate the current process.env against your schema.
+  Reports missing, invalid, and optional variables.
+
+${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("EXIT CODES")}
+  0  All variables pass validation
+  1  One or more variables are missing or invalid
+
+${color.bold("EXAMPLES")}
+  beacon check                             ${color.grey("# validate env")}
+  beacon check --profile production        ${color.grey("# validate with profile")}
+  beacon check -c ./config/beacon.json     ${color.grey("# custom config path")}
+`);
+    return;
+  }
+
+  console.log(`
+${color.bold("beacon")} ${color.dim("- validate env vars, config, secrets, and feature gates")}
+
+${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")}
+
+${color.bold("OPTIONS")}
+  -c, --config <path>  Path to config file (default: .beaconrc.json or beacon.config.json)
+  -o, --output <path>  Output file for init (default: .env.example)
+  --profile <name>     Profile name to use (e.g. staging, production)
+
+${color.bold("EXIT CODES")}
+  0  Success
+  1  Validation failure or error
+
+${color.bold("EXAMPLES")}
+  beacon init
+  beacon init --profile production
+  beacon check
+  beacon check -c ./config/beacon.json --profile staging
+  beacon help init
+`);
+}
+
+await main();

package/src/errors.ts

@@ -0,0 +1,18 @@
+export class ConfigError extends Error {
+  readonly key: string;
+  readonly redacted: boolean;
+
+  constructor(key: string, message: string, redacted = false) {
+    super(message);
+    this.name = "ConfigError";
+    this.key = key;
+    this.redacted = redacted;
+  }
+}
+
+export class ConfigValidationError extends AggregateError {
+  constructor(errors: ConfigError[]) {
+    super(errors, "Configuration validation failed");
+    this.name = "ConfigValidationError";
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,178 @@
+import { expect, test, beforeAll } from "bun:test";
+import { createBeacon, ConfigValidationError } from "./index";
+import { z } from "zod";
+
+const zodStringMin3 = z.string().min(3);
+
+const ORIGINAL_ENV = { ...process.env };
+
+beforeAll(() => {
+  process.env = { ...ORIGINAL_ENV };
+});
+
+test("returns typed config values after ensure()", () => {
+  process.env.DATABASE_URL = "https://example.com/db";
+  process.env.REDIS_URL = "https://example.com/redis";
+
+  const config = createBeacon({
+    DATABASE_URL: { type: "url", required: true },
+    REDIS_URL: { type: "url", required: true },
+  });
+
+  config.ensure();
+  expect(config.get<string>("DATABASE_URL")).toBe("https://example.com/db");
+  expect(config.get<string>("REDIS_URL")).toBe("https://example.com/redis");
+});
+
+test("throws ValidationError for missing required vars", () => {
+  delete process.env.MISSING_VAR;
+
+  const config = createBeacon({
+    MISSING_VAR: { type: "string", required: true },
+  });
+
+  expect(() => config.ensure()).toThrow(ConfigValidationError);
+});
+
+test("does not throw for optional vars with defaults", () => {
+  delete process.env.MY_PORT;
+
+  const config = createBeacon({
+    MY_PORT: { type: "port", default: 3000 },
+  });
+
+  config.ensure();
+  expect(config.get<number>("MY_PORT")).toBe(3000);
+});
+
+test("coerces number types", () => {
+  process.env.MY_NUMBER = "42";
+
+  const config = createBeacon({
+    MY_NUMBER: { type: "number" },
+  });
+
+  config.ensure();
+  expect(config.get<number>("MY_NUMBER")).toBe(42);
+});
+
+test("coerces boolean types", () => {
+  process.env.FEATURE_X = "true";
+  process.env.FEATURE_Y = "false";
+  process.env.FEATURE_Z = "1";
+
+  const config = createBeacon({
+    FEATURE_X: { type: "boolean" },
+    FEATURE_Y: { type: "boolean" },
+    FEATURE_Z: { type: "boolean" },
+  });
+
+  config.ensure();
+  expect(config.get<boolean>("FEATURE_X")).toBe(true);
+  expect(config.get<boolean>("FEATURE_Y")).toBe(false);
+  expect(config.get<boolean>("FEATURE_Z")).toBe(true);
+});
+
+test("validates enum values", () => {
+  process.env.NODE_ENV = "production";
+
+  const config = createBeacon({
+    NODE_ENV: {
+      type: "enum",
+      values: ["development", "staging", "production"],
+    },
+  });
+
+  config.ensure();
+  expect(config.get<string>("NODE_ENV")).toBe("production");
+});
+
+test("throws for invalid enum values", () => {
+  process.env.NODE_ENV = "invalid";
+
+  const config = createBeacon({
+    NODE_ENV: {
+      type: "enum",
+      values: ["development", "production"],
+    },
+  });
+
+  expect(() => config.ensure()).toThrow();
+});
+
+test("validates port range", () => {
+  process.env.PORT = "99999";
+
+  const config = createBeacon({
+    PORT: { type: "port" },
+  });
+
+  expect(() => config.ensure()).toThrow();
+});
+
+test("throws when accessing before ensure()", () => {
+  const config = createBeacon({
+    DB_URL: { type: "url", required: true },
+  });
+
+  expect(() => config.get("DB_URL")).toThrow("Call beacon.ensure()");
+});
+
+test("uses profile overrides when profile is set", () => {
+  process.env.DB_HOST = "prod.example.com";
+
+  const config = createBeacon(
+    {
+      DB_HOST: { type: "string" },
+    },
+    {
+      profile: "production",
+      profiles: {
+        production: {
+          DB_HOST: { type: "host" },
+        },
+      },
+    }
+  );
+
+  config.ensure();
+  expect(config.get<string>("DB_HOST")).toBe("prod.example.com");
+});
+
+test("accepts Zod schemas directly", () => {
+  process.env.ZOD_VAR = "hello";
+
+  const config = createBeacon({
+    ZOD_VAR: { schema: zodStringMin3 },
+  });
+
+  config.ensure();
+  expect(config.get<string>("ZOD_VAR")).toBe("hello");
+});
+
+test("collects all errors before throwing", () => {
+  delete process.env.VAR_A;
+  delete process.env.VAR_B;
+
+  const config = createBeacon({
+    VAR_A: { type: "string", required: true },
+    VAR_B: { type: "number", required: true },
+  });
+
+  try {
+    config.ensure();
+    expect.unreachable();
+  } catch (err) {
+    expect(err).toBeInstanceOf(ConfigValidationError);
+    expect((err as ConfigValidationError).errors).toHaveLength(2);
+  }
+});
+
+test("tracks secret keys", () => {
+  const config = createBeacon({
+    API_KEY: { type: "string", secret: true },
+    DB_URL: { type: "url" },
+  });
+
+  expect(config.secret).toEqual({ API_KEY: true });
+});