@bladedev/envguard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bladedevoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# envguard
+
+Type-safe `.env` for Node.js. Define a schema, get validation + TypeScript types + CLI.
+
+Stop discovering missing env vars at runtime.
+
+## Install
+
+```bash
+npm install @bladedev/envguard
+```
+
+## Usage
+
+```ts
+// env.schema.ts
+import { envguard, t } from '@bladedev/envguard'
+
+export default envguard({
+  DATABASE_URL: t.url({ required: true }),
+  PORT: t.port({ default: 3000 }),
+  NODE_ENV: t.enum(['development', 'staging', 'production']),
+  DEBUG: t.boolean({ default: false }),
+  API_KEY: t.string({ secret: true }),
+})
+```
+
+```ts
+// app.ts
+import env from './env.schema'
+
+console.log(env.PORT)      // number
+console.log(env.NODE_ENV)  // 'development' | 'staging' | 'production'
+```
+
+Full autocomplete. Zero runtime surprises.
+
+## CLI
+
+```bash
+# Validate .env against schema
+npx envguard check
+
+# Generate schema from existing .env
+npx envguard init
+```
+
+```
+✗ envguard: 2 problems found
+
+  DATABASE_URL  ✗ required but missing
+  PORT          ✗ "abc" is not a valid port (expected 1-65535)
+
+  1 variable OK, 2 failed
+```
+
+## Types
+
+| Helper | Output | Validates |
+|---|---|---|
+| `t.string()` | `string` | Non-empty |
+| `t.number()` | `number` | Numeric |
+| `t.boolean()` | `boolean` | true/false, 1/0, yes/no |
+| `t.port()` | `number` | 1–65535 |
+| `t.url()` | `string` | Valid URL |
+| `t.email()` | `string` | Valid email |
+| `t.enum([...])` | Literal union | One of values |
+| `t.json<T>()` | `T` | Valid JSON |
+
+Every helper accepts `{ required, default, secret }`.
+
+## Options
+
+```ts
+envguard(schema, {
+  path: '.env',       // default: reads process.env
+  onError: 'throw',   // 'throw' | 'exit' | 'warn' (default: 'exit')
+})
+```
+
+## vs. alternatives
+
+| | dotenv | envalid | t3-env | **envguard** |
+|---|---|---|---|---|
+| .env parsing | ✓ | ✗ | ✗ | ✓ |
+| Validation | ✗ | ✓ | ✓ | ✓ |
+| TS inference | ✗ | Partial | ✓ | ✓ |
+| CLI tools | ✗ | ✗ | ✗ | ✓ |
+
+## License
+
+MIT

package/dist/cli/index.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { defineCommand as defineCommand3, runMain } from "citty";
+
+// src/cli/commands/check.ts
+import { defineCommand } from "citty";
+import { readFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+import { createJiti } from "jiti";
+
+// src/core/parser.ts
+function parse(input) {
+  const result = {};
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const stripped = line.startsWith("export ") ? line.slice(7) : line;
+    const eqIndex = stripped.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = stripped.slice(0, eqIndex).trim();
+    result[key] = parseValue(stripped.slice(eqIndex + 1));
+  }
+  return result;
+}
+function parseValue(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/\\([nrt"\\])/g, (_, ch) => {
+      const map = { n: "\n", r: "\r", t: "	", '"': '"', "\\": "\\" };
+      return map[ch] ?? ch;
+    });
+  }
+  const commentIndex = trimmed.indexOf(" #");
+  if (commentIndex !== -1) {
+    return trimmed.slice(0, commentIndex).trim();
+  }
+  return trimmed;
+}
+
+// src/core/validator.ts
+function validate(schema, parsed) {
+  const errors = [];
+  const env = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const raw = parsed[key];
+    if (raw === void 0) {
+      if (field._default !== void 0) {
+        env[key] = field._default;
+        continue;
+      }
+      if (field._required) {
+        errors.push({ key, message: "required but missing" });
+        continue;
+      }
+      env[key] = void 0;
+      continue;
+    }
+    const result = field._validate(raw);
+    if (result.success) {
+      env[key] = result.value;
+    } else {
+      errors.push({ key, message: result.message, received: raw });
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, env };
+}
+
+// src/cli/resolve-config.ts
+import { existsSync } from "fs";
+import { resolve } from "path";
+var CONFIG_NAMES = ["envguard.config.ts", "env.schema.ts"];
+function resolveConfigPath(explicit) {
+  if (explicit) {
+    const p = resolve(explicit);
+    if (!existsSync(p)) throw new Error(`Config file not found: ${p}`);
+    return p;
+  }
+  for (const name of CONFIG_NAMES) {
+    const p = resolve(process.cwd(), name);
+    if (existsSync(p)) return p;
+  }
+  throw new Error(
+    `No envguard config found. Expected one of:
+${CONFIG_NAMES.map((n) => `  - ${n}`).join("\n")}`
+  );
+}
+
+// src/cli/reporter.ts
+function formatCheckResult(errors, total) {
+  if (errors.length === 0) return `
+\u2713 envguard: all ${total} variables OK
+`;
+  const pad = Math.max(...errors.map((e) => e.key.length));
+  const lines = errors.map((e) => `  ${e.key.padEnd(pad)}  \u2717 ${e.message}`);
+  const passed = total - errors.length;
+  return [
+    "",
+    `\u2717 envguard: ${errors.length} problem${errors.length > 1 ? "s" : ""} found`,
+    "",
+    ...lines,
+    "",
+    `  ${passed} variable${passed !== 1 ? "s" : ""} OK, ${errors.length} failed`,
+    ""
+  ].join("\n");
+}
+
+// src/cli/commands/check.ts
+var jiti = createJiti(import.meta.url);
+var checkCommand = defineCommand({
+  meta: { name: "check", description: "Validate .env against schema" },
+  args: {
+    config: { type: "string", description: "Path to config file" },
+    env: { type: "string", description: "Path to .env file", default: ".env" }
+  },
+  async run({ args }) {
+    const configPath = resolveConfigPath(args.config);
+    const mod = await jiti.import(configPath);
+    const schema = mod.default || mod;
+    const envPath = resolve2(args.env);
+    const content = readFileSync(envPath, "utf-8");
+    const parsed = parse(content);
+    const result = validate(schema, parsed);
+    const total = Object.keys(schema).length;
+    if (result.ok) {
+      process.stdout.write(formatCheckResult([], total));
+      process.exit(0);
+    } else {
+      process.stdout.write(formatCheckResult(result.errors, total));
+      process.exit(1);
+    }
+  }
+});
+
+// src/cli/commands/init.ts
+import { defineCommand as defineCommand2 } from "citty";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync2 } from "fs";
+import { resolve as resolve3 } from "path";
+var SECRET_PATTERNS = ["key", "secret", "token", "password", "pass", "credential", "auth"];
+function inferType(key, value) {
+  const lower = key.toLowerCase();
+  const isSecret = SECRET_PATTERNS.some((p) => lower.includes(p));
+  if (lower.includes("port")) return "t.port()";
+  try {
+    new URL(value);
+    return "t.url()";
+  } catch {
+  }
+  if (["true", "false", "1", "0", "yes", "no"].includes(value.toLowerCase())) return "t.boolean()";
+  if (value !== "" && !isNaN(Number(value))) return "t.number()";
+  return isSecret ? "t.string({ secret: true })" : "t.string()";
+}
+function generateSchema(vars) {
+  const fields = Object.entries(vars).map(([k, v]) => `  ${k}: ${inferType(k, v)},`).join("\n");
+  return `import { envguard, t } from 'envguard'
+
+export default envguard({
+${fields}
+})
+`;
+}
+var initCommand = defineCommand2({
+  meta: { name: "init", description: "Generate env.schema.ts from existing .env" },
+  args: {
+    env: { type: "string", description: "Path to .env file", default: ".env" },
+    output: { type: "string", description: "Output file", default: "env.schema.ts" }
+  },
+  async run({ args }) {
+    const envPath = resolve3(args.env);
+    if (!existsSync2(envPath)) {
+      console.error(`File not found: ${envPath}`);
+      process.exit(1);
+    }
+    const outputPath = resolve3(args.output);
+    if (existsSync2(outputPath)) {
+      console.error(`File already exists: ${outputPath}`);
+      process.exit(1);
+    }
+    const parsed = parse(readFileSync2(envPath, "utf-8"));
+    writeFileSync(outputPath, generateSchema(parsed));
+    console.log(`\u2713 Scanned ${args.env} (${Object.keys(parsed).length} variables)`);
+    console.log(`\u2713 Generated ${args.output}`);
+  }
+});
+
+// src/cli/index.ts
+var main = defineCommand3({
+  meta: { name: "envguard", version: "0.1.0", description: "Type-safe .env manager" },
+  subCommands: {
+    check: checkCommand,
+    init: initCommand
+  }
+});
+runMain(main);

package/dist/index.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  EnvValidationError: () => EnvValidationError,
+  envguard: () => envguard,
+  t: () => t
+});
+module.exports = __toCommonJS(src_exports);
+var import_node_fs = require("fs");
+
+// src/core/parser.ts
+function parse(input) {
+  const result = {};
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const stripped = line.startsWith("export ") ? line.slice(7) : line;
+    const eqIndex = stripped.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = stripped.slice(0, eqIndex).trim();
+    result[key] = parseValue(stripped.slice(eqIndex + 1));
+  }
+  return result;
+}
+function parseValue(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/\\([nrt"\\])/g, (_, ch) => {
+      const map = { n: "\n", r: "\r", t: "	", '"': '"', "\\": "\\" };
+      return map[ch] ?? ch;
+    });
+  }
+  const commentIndex = trimmed.indexOf(" #");
+  if (commentIndex !== -1) {
+    return trimmed.slice(0, commentIndex).trim();
+  }
+  return trimmed;
+}
+
+// src/core/validator.ts
+function validate(schema, parsed) {
+  const errors = [];
+  const env = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const raw = parsed[key];
+    if (raw === void 0) {
+      if (field._default !== void 0) {
+        env[key] = field._default;
+        continue;
+      }
+      if (field._required) {
+        errors.push({ key, message: "required but missing" });
+        continue;
+      }
+      env[key] = void 0;
+      continue;
+    }
+    const result = field._validate(raw);
+    if (result.success) {
+      env[key] = result.value;
+    } else {
+      errors.push({ key, message: result.message, received: raw });
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, env };
+}
+
+// src/core/errors.ts
+var EnvValidationError = class extends Error {
+  errors;
+  constructor(errors) {
+    super(`envguard: ${errors.length} problem${errors.length > 1 ? "s" : ""} found`);
+    this.name = "EnvValidationError";
+    this.errors = errors;
+  }
+};
+
+// src/core/schema.ts
+var import_v4 = require("zod/v4");
+function createField(opts, validate2) {
+  return {
+    _type: void 0,
+    _required: opts.default !== void 0 ? false : opts.required ?? true,
+    _default: opts.default,
+    _secret: opts.secret ?? false,
+    _parse(raw) {
+      const r = validate2(raw);
+      if (!r.success) throw new Error(r.message);
+      return r.value;
+    },
+    _validate: validate2
+  };
+}
+var _emailSchema = null;
+var t = {
+  string(opts = {}) {
+    return createField(
+      opts,
+      (raw) => raw.length > 0 ? { success: true, value: raw } : { success: false, message: "expected non-empty string" }
+    );
+  },
+  number(opts = {}) {
+    return createField(opts, (raw) => {
+      const n = Number(raw);
+      return !isNaN(n) && raw.trim() !== "" ? { success: true, value: n } : { success: false, message: `"${raw}" is not a valid number` };
+    });
+  },
+  boolean(opts = {}) {
+    const truthy = /* @__PURE__ */ new Set(["true", "1", "yes"]);
+    const falsy = /* @__PURE__ */ new Set(["false", "0", "no"]);
+    return createField(opts, (raw) => {
+      const v = raw.toLowerCase();
+      if (truthy.has(v)) return { success: true, value: true };
+      if (falsy.has(v)) return { success: true, value: false };
+      return { success: false, message: `expected true/false, 1/0, or yes/no \u2014 got "${raw}"` };
+    });
+  },
+  port(opts = {}) {
+    return createField(opts, (raw) => {
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        return { success: false, message: `"${raw}" is not a valid port (expected 1-65535)` };
+      }
+      return { success: true, value: n };
+    });
+  },
+  url(opts = {}) {
+    return createField(opts, (raw) => {
+      try {
+        new URL(raw);
+        return { success: true, value: raw };
+      } catch {
+        return { success: false, message: `invalid URL: "${raw}"` };
+      }
+    });
+  },
+  email(opts = {}) {
+    return createField(opts, (raw) => {
+      _emailSchema ??= import_v4.z.string().email();
+      return _emailSchema.safeParse(raw).success ? { success: true, value: raw } : { success: false, message: `invalid email: "${raw}"` };
+    });
+  },
+  enum(values, opts = {}) {
+    return createField(
+      opts,
+      (raw) => values.includes(raw) ? { success: true, value: raw } : { success: false, message: `"${raw}" is not one of: ${values.join(", ")}` }
+    );
+  },
+  json(opts = {}) {
+    return createField(opts, (raw) => {
+      try {
+        return { success: true, value: JSON.parse(raw) };
+      } catch {
+        return { success: false, message: `invalid JSON` };
+      }
+    });
+  }
+};
+
+// src/index.ts
+function formatErrors(errors) {
+  const lines = errors.map((e) => `  ${e.key}: ${e.message}${e.received !== void 0 ? ` (got: ${e.received})` : ""}`);
+  return `envguard validation failed:
+${lines.join("\n")}`;
+}
+function envguard(schema, opts = {}) {
+  const { path, onError = "exit" } = opts;
+  const raw = path ? parse((0, import_node_fs.readFileSync)(path, "utf8")) : process.env;
+  const result = validate(schema, raw);
+  if (!result.ok) {
+    const msg = formatErrors(result.errors);
+    if (onError === "throw") throw new EnvValidationError(result.errors);
+    if (onError === "warn") {
+      console.warn(msg);
+      return {};
+    }
+    console.error(msg);
+    process.exit(1);
+  }
+  return result.env;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EnvValidationError,
+  envguard,
+  t
+});

package/dist/index.d.cts

@@ -0,0 +1,51 @@
+interface FieldOptions<T = unknown> {
+    required?: boolean;
+    default?: T;
+    secret?: boolean;
+}
+interface SchemaField<T = unknown> {
+    _type: T;
+    _required: boolean;
+    _default: T | undefined;
+    _secret: boolean;
+    _parse: (raw: string) => T;
+    _validate: (raw: string) => {
+        success: true;
+        value: T;
+    } | {
+        success: false;
+        message: string;
+    };
+}
+type Schema = Record<string, SchemaField>;
+interface ValidationError {
+    key: string;
+    message: string;
+    received?: string;
+}
+
+declare class EnvValidationError extends Error {
+    errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+
+declare const t: {
+    string(opts?: FieldOptions<string>): SchemaField<string>;
+    number(opts?: FieldOptions<number>): SchemaField<number>;
+    boolean(opts?: FieldOptions<boolean>): SchemaField<boolean>;
+    port(opts?: FieldOptions<number>): SchemaField<number>;
+    url(opts?: FieldOptions<string>): SchemaField<string>;
+    email(opts?: FieldOptions<string>): SchemaField<string>;
+    enum<const T extends string>(values: T[], opts?: FieldOptions<T>): SchemaField<T>;
+    json<T = unknown>(opts?: FieldOptions<T>): SchemaField<T>;
+};
+
+interface EnvguardOptions {
+    path?: string;
+    onError?: 'throw' | 'warn' | 'exit';
+}
+declare function envguard<S extends Schema>(schema: S, opts?: EnvguardOptions): {
+    [K in keyof S]: S[K]['_type'];
+};
+
+export { EnvValidationError, type ValidationError, envguard, t };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+interface FieldOptions<T = unknown> {
+    required?: boolean;
+    default?: T;
+    secret?: boolean;
+}
+interface SchemaField<T = unknown> {
+    _type: T;
+    _required: boolean;
+    _default: T | undefined;
+    _secret: boolean;
+    _parse: (raw: string) => T;
+    _validate: (raw: string) => {
+        success: true;
+        value: T;
+    } | {
+        success: false;
+        message: string;
+    };
+}
+type Schema = Record<string, SchemaField>;
+interface ValidationError {
+    key: string;
+    message: string;
+    received?: string;
+}
+
+declare class EnvValidationError extends Error {
+    errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+
+declare const t: {
+    string(opts?: FieldOptions<string>): SchemaField<string>;
+    number(opts?: FieldOptions<number>): SchemaField<number>;
+    boolean(opts?: FieldOptions<boolean>): SchemaField<boolean>;
+    port(opts?: FieldOptions<number>): SchemaField<number>;
+    url(opts?: FieldOptions<string>): SchemaField<string>;
+    email(opts?: FieldOptions<string>): SchemaField<string>;
+    enum<const T extends string>(values: T[], opts?: FieldOptions<T>): SchemaField<T>;
+    json<T = unknown>(opts?: FieldOptions<T>): SchemaField<T>;
+};
+
+interface EnvguardOptions {
+    path?: string;
+    onError?: 'throw' | 'warn' | 'exit';
+}
+declare function envguard<S extends Schema>(schema: S, opts?: EnvguardOptions): {
+    [K in keyof S]: S[K]['_type'];
+};
+
+export { EnvValidationError, type ValidationError, envguard, t };

package/dist/index.js

@@ -0,0 +1,184 @@
+// src/index.ts
+import { readFileSync } from "fs";
+
+// src/core/parser.ts
+function parse(input) {
+  const result = {};
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const stripped = line.startsWith("export ") ? line.slice(7) : line;
+    const eqIndex = stripped.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = stripped.slice(0, eqIndex).trim();
+    result[key] = parseValue(stripped.slice(eqIndex + 1));
+  }
+  return result;
+}
+function parseValue(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/\\([nrt"\\])/g, (_, ch) => {
+      const map = { n: "\n", r: "\r", t: "	", '"': '"', "\\": "\\" };
+      return map[ch] ?? ch;
+    });
+  }
+  const commentIndex = trimmed.indexOf(" #");
+  if (commentIndex !== -1) {
+    return trimmed.slice(0, commentIndex).trim();
+  }
+  return trimmed;
+}
+
+// src/core/validator.ts
+function validate(schema, parsed) {
+  const errors = [];
+  const env = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const raw = parsed[key];
+    if (raw === void 0) {
+      if (field._default !== void 0) {
+        env[key] = field._default;
+        continue;
+      }
+      if (field._required) {
+        errors.push({ key, message: "required but missing" });
+        continue;
+      }
+      env[key] = void 0;
+      continue;
+    }
+    const result = field._validate(raw);
+    if (result.success) {
+      env[key] = result.value;
+    } else {
+      errors.push({ key, message: result.message, received: raw });
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, env };
+}
+
+// src/core/errors.ts
+var EnvValidationError = class extends Error {
+  errors;
+  constructor(errors) {
+    super(`envguard: ${errors.length} problem${errors.length > 1 ? "s" : ""} found`);
+    this.name = "EnvValidationError";
+    this.errors = errors;
+  }
+};
+
+// src/core/schema.ts
+import { z } from "zod/v4";
+function createField(opts, validate2) {
+  return {
+    _type: void 0,
+    _required: opts.default !== void 0 ? false : opts.required ?? true,
+    _default: opts.default,
+    _secret: opts.secret ?? false,
+    _parse(raw) {
+      const r = validate2(raw);
+      if (!r.success) throw new Error(r.message);
+      return r.value;
+    },
+    _validate: validate2
+  };
+}
+var _emailSchema = null;
+var t = {
+  string(opts = {}) {
+    return createField(
+      opts,
+      (raw) => raw.length > 0 ? { success: true, value: raw } : { success: false, message: "expected non-empty string" }
+    );
+  },
+  number(opts = {}) {
+    return createField(opts, (raw) => {
+      const n = Number(raw);
+      return !isNaN(n) && raw.trim() !== "" ? { success: true, value: n } : { success: false, message: `"${raw}" is not a valid number` };
+    });
+  },
+  boolean(opts = {}) {
+    const truthy = /* @__PURE__ */ new Set(["true", "1", "yes"]);
+    const falsy = /* @__PURE__ */ new Set(["false", "0", "no"]);
+    return createField(opts, (raw) => {
+      const v = raw.toLowerCase();
+      if (truthy.has(v)) return { success: true, value: true };
+      if (falsy.has(v)) return { success: true, value: false };
+      return { success: false, message: `expected true/false, 1/0, or yes/no \u2014 got "${raw}"` };
+    });
+  },
+  port(opts = {}) {
+    return createField(opts, (raw) => {
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        return { success: false, message: `"${raw}" is not a valid port (expected 1-65535)` };
+      }
+      return { success: true, value: n };
+    });
+  },
+  url(opts = {}) {
+    return createField(opts, (raw) => {
+      try {
+        new URL(raw);
+        return { success: true, value: raw };
+      } catch {
+        return { success: false, message: `invalid URL: "${raw}"` };
+      }
+    });
+  },
+  email(opts = {}) {
+    return createField(opts, (raw) => {
+      _emailSchema ??= z.string().email();
+      return _emailSchema.safeParse(raw).success ? { success: true, value: raw } : { success: false, message: `invalid email: "${raw}"` };
+    });
+  },
+  enum(values, opts = {}) {
+    return createField(
+      opts,
+      (raw) => values.includes(raw) ? { success: true, value: raw } : { success: false, message: `"${raw}" is not one of: ${values.join(", ")}` }
+    );
+  },
+  json(opts = {}) {
+    return createField(opts, (raw) => {
+      try {
+        return { success: true, value: JSON.parse(raw) };
+      } catch {
+        return { success: false, message: `invalid JSON` };
+      }
+    });
+  }
+};
+
+// src/index.ts
+function formatErrors(errors) {
+  const lines = errors.map((e) => `  ${e.key}: ${e.message}${e.received !== void 0 ? ` (got: ${e.received})` : ""}`);
+  return `envguard validation failed:
+${lines.join("\n")}`;
+}
+function envguard(schema, opts = {}) {
+  const { path, onError = "exit" } = opts;
+  const raw = path ? parse(readFileSync(path, "utf8")) : process.env;
+  const result = validate(schema, raw);
+  if (!result.ok) {
+    const msg = formatErrors(result.errors);
+    if (onError === "throw") throw new EnvValidationError(result.errors);
+    if (onError === "warn") {
+      console.warn(msg);
+      return {};
+    }
+    console.error(msg);
+    process.exit(1);
+  }
+  return result.env;
+}
+export {
+  EnvValidationError,
+  envguard,
+  t
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@bladedev/envguard",
+  "version": "0.1.0",
+  "description": "Type-safe .env manager — schema, validation, sync, CLI",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "bin": {
+    "envguard": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "env",
+    "dotenv",
+    "validation",
+    "typescript",
+    "schema",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bladedevoff/envguard"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "citty": "^0.2.1",
+    "jiti": "^2.6.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}