ultraenv 1.0.0

package/dist/middleware/fastify.cjs

@@ -0,0 +1,91 @@
+"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/middleware/fastify.ts
+var fastify_exports = {};
+__export(fastify_exports, {
+  createUltraenvPlugin: () => createUltraenvPlugin,
+  ultraenvPlugin: () => ultraenvPlugin
+});
+module.exports = __toCommonJS(fastify_exports);
+function ultraenvPlugin(fastify, options = {}, done) {
+  const {
+    expose = true,
+    prefix = "PUBLIC_",
+    additionalPrefixes = [],
+    allowList = [],
+    denyList = [],
+    exposeNodeEnv = true,
+    source = process.env,
+    schema: _schema
+  } = options;
+  if (!expose) {
+    done();
+    return;
+  }
+  const allPrefixes = [prefix];
+  for (const p of additionalPrefixes) {
+    allPrefixes.push(p);
+  }
+  const allowSet = new Set(allowList.map((k) => k.toUpperCase()));
+  const denySet = new Set(denyList.map((k) => k.toUpperCase()));
+  const filteredEnv = buildFastifyEnv(
+    source,
+    allPrefixes,
+    allowSet,
+    denySet,
+    exposeNodeEnv
+  );
+  fastify.decorate("env", filteredEnv);
+  done();
+}
+function buildFastifyEnv(source, prefixes, allowSet, denySet, exposeNodeEnv) {
+  const env = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === void 0 || value === "") continue;
+    const upperKey = key.toUpperCase();
+    if (denySet.has(upperKey)) continue;
+    if (allowSet.has(upperKey)) {
+      env[key] = value;
+      continue;
+    }
+    if (exposeNodeEnv && upperKey === "NODE_ENV") {
+      env[key] = value;
+      continue;
+    }
+    for (const p of prefixes) {
+      if (upperKey.startsWith(p.toUpperCase())) {
+        env[key] = value;
+        break;
+      }
+    }
+  }
+  return env;
+}
+function createUltraenvPlugin(_opts = {}) {
+  return {
+    name: "ultraenv",
+    handler: ultraenvPlugin
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createUltraenvPlugin,
+  ultraenvPlugin
+});

package/dist/middleware/fastify.d.cts

@@ -0,0 +1,111 @@
+/** Options for the ultraenv Fastify plugin */
+interface UltraenvPluginOptions {
+    /**
+     * Whether to expose env vars on the fastify instance.
+     * Default: true
+     */
+    expose?: boolean;
+    /**
+     * Prefix to filter public variables by.
+     * Only env vars starting with this prefix will be included in fastify.env.
+     * Default: 'PUBLIC_'
+     */
+    prefix?: string;
+    /**
+     * Additional prefixes to include.
+     * Default: []
+     */
+    additionalPrefixes?: readonly string[];
+    /**
+     * Explicit allow-list of env var names to always include.
+     * Default: []
+     */
+    allowList?: readonly string[];
+    /**
+     * Explicit deny-list of env var names to always exclude.
+     * Default: []
+     */
+    denyList?: readonly string[];
+    /**
+     * Whether to include NODE_ENV.
+     * Default: true
+     */
+    exposeNodeEnv?: boolean;
+    /**
+     * Custom env source. Defaults to process.env.
+     */
+    source?: Record<string, string | undefined>;
+    /**
+     * An optional JSON schema for validating environment variables.
+     * If provided, the plugin will validate all env vars against this schema
+     * at registration time and throw if validation fails.
+     *
+     * The schema should follow the standard JSON Schema format.
+     */
+    schema?: Record<string, unknown>;
+}
+/** The filtered env object attached to the Fastify instance */
+interface FastifyEnv {
+    /** The filtered environment variables */
+    [key: string]: string;
+}
+/**
+ * Fastify plugin that decorates the Fastify instance with a filtered
+ * environment variable object.
+ *
+ * The env object is built once at plugin registration time and attached
+ * as `fastify.env`. Individual route handlers can then access filtered
+ * env vars safely.
+ *
+ * @param fastify - The Fastify instance
+ * @param options - Plugin options
+ * @param done - Callback to signal plugin registration is complete
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { ultraenvPlugin } from 'ultraenv/fastify';
+ *
+ * const fastify = Fastify();
+ * fastify.register(ultraenvPlugin, {
+ *   prefix: 'PUBLIC_',
+ *   additionalPrefixes: ['NEXT_PUBLIC_'],
+ * });
+ *
+ * // In routes:
+ * fastify.get('/api/config', async (request, reply) => {
+ *   return { apiUrl: fastify.env.PUBLIC_API_URL };
+ * });
+ * ```
+ */
+declare function ultraenvPlugin(fastify: FastifyInstance, options: UltraenvPluginOptions | undefined, done: () => void): void;
+/**
+ * Minimal Fastify instance interface needed by the plugin.
+ * This avoids a hard dependency on the 'fastify' package while
+ * maintaining type safety.
+ */
+interface FastifyInstance {
+    /**
+     * Decorate the Fastify instance with a new property.
+     */
+    decorate(property: string, value: unknown): FastifyInstance;
+}
+/**
+ * Helper to create a properly typed Fastify plugin object.
+ * This is the recommended way to register the plugin with TypeScript.
+ *
+ * @param opts - Plugin options
+ * @returns A Fastify plugin object compatible with fastify.register()
+ *
+ * @example
+ * ```typescript
+ * import { createUltraenvPlugin } from 'ultraenv/fastify';
+ * fastify.register(createUltraenvPlugin({ prefix: 'PUBLIC_' }));
+ * ```
+ */
+declare function createUltraenvPlugin(_opts?: UltraenvPluginOptions): {
+    name: string;
+    handler: (instance: FastifyInstance, options: UltraenvPluginOptions | undefined, done: () => void) => void;
+};
+
+export { type FastifyEnv, type FastifyInstance, type UltraenvPluginOptions, createUltraenvPlugin, ultraenvPlugin };

package/dist/middleware/fastify.d.ts

@@ -0,0 +1,111 @@
+/** Options for the ultraenv Fastify plugin */
+interface UltraenvPluginOptions {
+    /**
+     * Whether to expose env vars on the fastify instance.
+     * Default: true
+     */
+    expose?: boolean;
+    /**
+     * Prefix to filter public variables by.
+     * Only env vars starting with this prefix will be included in fastify.env.
+     * Default: 'PUBLIC_'
+     */
+    prefix?: string;
+    /**
+     * Additional prefixes to include.
+     * Default: []
+     */
+    additionalPrefixes?: readonly string[];
+    /**
+     * Explicit allow-list of env var names to always include.
+     * Default: []
+     */
+    allowList?: readonly string[];
+    /**
+     * Explicit deny-list of env var names to always exclude.
+     * Default: []
+     */
+    denyList?: readonly string[];
+    /**
+     * Whether to include NODE_ENV.
+     * Default: true
+     */
+    exposeNodeEnv?: boolean;
+    /**
+     * Custom env source. Defaults to process.env.
+     */
+    source?: Record<string, string | undefined>;
+    /**
+     * An optional JSON schema for validating environment variables.
+     * If provided, the plugin will validate all env vars against this schema
+     * at registration time and throw if validation fails.
+     *
+     * The schema should follow the standard JSON Schema format.
+     */
+    schema?: Record<string, unknown>;
+}
+/** The filtered env object attached to the Fastify instance */
+interface FastifyEnv {
+    /** The filtered environment variables */
+    [key: string]: string;
+}
+/**
+ * Fastify plugin that decorates the Fastify instance with a filtered
+ * environment variable object.
+ *
+ * The env object is built once at plugin registration time and attached
+ * as `fastify.env`. Individual route handlers can then access filtered
+ * env vars safely.
+ *
+ * @param fastify - The Fastify instance
+ * @param options - Plugin options
+ * @param done - Callback to signal plugin registration is complete
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { ultraenvPlugin } from 'ultraenv/fastify';
+ *
+ * const fastify = Fastify();
+ * fastify.register(ultraenvPlugin, {
+ *   prefix: 'PUBLIC_',
+ *   additionalPrefixes: ['NEXT_PUBLIC_'],
+ * });
+ *
+ * // In routes:
+ * fastify.get('/api/config', async (request, reply) => {
+ *   return { apiUrl: fastify.env.PUBLIC_API_URL };
+ * });
+ * ```
+ */
+declare function ultraenvPlugin(fastify: FastifyInstance, options: UltraenvPluginOptions | undefined, done: () => void): void;
+/**
+ * Minimal Fastify instance interface needed by the plugin.
+ * This avoids a hard dependency on the 'fastify' package while
+ * maintaining type safety.
+ */
+interface FastifyInstance {
+    /**
+     * Decorate the Fastify instance with a new property.
+     */
+    decorate(property: string, value: unknown): FastifyInstance;
+}
+/**
+ * Helper to create a properly typed Fastify plugin object.
+ * This is the recommended way to register the plugin with TypeScript.
+ *
+ * @param opts - Plugin options
+ * @returns A Fastify plugin object compatible with fastify.register()
+ *
+ * @example
+ * ```typescript
+ * import { createUltraenvPlugin } from 'ultraenv/fastify';
+ * fastify.register(createUltraenvPlugin({ prefix: 'PUBLIC_' }));
+ * ```
+ */
+declare function createUltraenvPlugin(_opts?: UltraenvPluginOptions): {
+    name: string;
+    handler: (instance: FastifyInstance, options: UltraenvPluginOptions | undefined, done: () => void) => void;
+};
+
+export { type FastifyEnv, type FastifyInstance, type UltraenvPluginOptions, createUltraenvPlugin, ultraenvPlugin };

package/dist/middleware/fastify.js

@@ -0,0 +1,8 @@
+import {
+  createUltraenvPlugin,
+  ultraenvPlugin
+} from "../chunk-JB7RKV3C.js";
+export {
+  createUltraenvPlugin,
+  ultraenvPlugin
+};

package/dist/module-IDIZPP4M.js

@@ -0,0 +1,10 @@
+import {
+  generateModule,
+  generateModuleContent
+} from "./chunk-YMMP4VQL.js";
+import "./chunk-3VYXPTYV.js";
+import "./chunk-5G2DU52U.js";
+export {
+  generateModule,
+  generateModuleContent
+};

package/dist/protect-NCWPM6VC.js

@@ -0,0 +1,161 @@
+import {
+  drawBox
+} from "./chunk-TMT5KCO3.js";
+import {
+  getTrackedFiles,
+  isGitIgnored,
+  isGitRepository
+} from "./chunk-R7PZRSZ7.js";
+import {
+  bold,
+  green,
+  red,
+  yellow
+} from "./chunk-OMAOROL4.js";
+import {
+  writeError,
+  writeJson,
+  writeLine
+} from "./chunk-YN2KGTCB.js";
+import {
+  exists,
+  readFile
+} from "./chunk-3VYXPTYV.js";
+import "./chunk-5G2DU52U.js";
+
+// src/cli/commands/protect.ts
+import { resolve, join } from "path";
+var PROTECTED_PATTERNS = [
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  ".env.vault",
+  ".env.keys"
+];
+async function run(args, ctx) {
+  try {
+    const cwd = args.flags["--cwd"] ?? ctx.cwd;
+    const baseDir = resolve(cwd);
+    if (ctx.outputFormat === "json") {
+      return await checkProtectionJson(baseDir);
+    }
+    writeLine(bold("\u{1F6E1}\uFE0F  .gitignore Protection Check"));
+    writeLine("");
+    const isGit = await isGitRepository(baseDir);
+    if (!isGit) {
+      writeLine(yellow("  \u26A0 Not a git repository. Protection check is limited."));
+      writeLine("");
+    }
+    const gitignorePath = join(baseDir, ".gitignore");
+    const gitignoreExists = await exists(gitignorePath);
+    if (!gitignoreExists) {
+      writeError(red("  \u2717 No .gitignore file found!"));
+      writeLine("");
+      const box = drawBox([
+        "Your project has no .gitignore file.",
+        "Secrets in .env files could be committed to version control.",
+        "Create a .gitignore with ultraenv entries:",
+        "",
+        "  ultraenv init"
+      ], { title: "DANGER", border: "double" });
+      writeLine(box);
+      writeLine("");
+      return 1;
+    }
+    writeLine(green("  \u2713 .gitignore exists"));
+    const gitignoreContent = await readFile(gitignorePath);
+    const issues = [];
+    const protectedEntries = [];
+    for (const pattern of PROTECTED_PATTERNS) {
+      if (gitignoreContent.includes(pattern)) {
+        protectedEntries.push(pattern);
+      } else {
+        issues.push(pattern);
+      }
+    }
+    writeLine(green(`  \u2713 ${protectedEntries.length}/${PROTECTED_PATTERNS.length} patterns protected`));
+    const envFiles = [".env", ".env.local", ".env.production", ".env.development"];
+    const notIgnored = [];
+    for (const envFile of envFiles) {
+      const envPath = join(baseDir, envFile);
+      const fileExists = await exists(envPath);
+      if (!fileExists) continue;
+      const ignored = await isGitIgnored(envFile, baseDir);
+      if (!ignored) {
+        notIgnored.push(envFile);
+      }
+    }
+    if (notIgnored.length > 0) {
+      writeLine("");
+      writeError(red(`  \u2717 ${notIgnored.length} .env file(s) are NOT gitignored:`));
+      for (const f of notIgnored) {
+        writeError(red(`    - ${f}`));
+      }
+    }
+    if (isGit) {
+      const trackedFiles = await getTrackedFiles(baseDir);
+      const trackedEnvFiles = trackedFiles.filter(
+        (f) => f.startsWith(".env") && !f.endsWith(".example")
+      );
+      if (trackedEnvFiles.length > 0) {
+        writeLine("");
+        writeError(red(bold(`  \u26A0 ${trackedEnvFiles.length} .env file(s) are tracked by git:`)));
+        for (const f of trackedEnvFiles) {
+          writeError(red(`    - ${f}`));
+        }
+        writeLine("");
+        const warnBox = drawBox([
+          "Tracked .env files may contain secrets.",
+          "Remove them from version control immediately:",
+          "",
+          "  git rm --cached .env*",
+          '  git commit -m "Remove tracked .env files"'
+        ], { title: "WARNING", border: "double" });
+        writeLine(warnBox);
+        writeLine("");
+        return 1;
+      }
+    }
+    if (issues.length > 0) {
+      writeLine("");
+      writeLine(yellow(`  Missing patterns:`));
+      for (const p of issues) {
+        writeLine(yellow(`    - ${p}`));
+      }
+      writeLine("");
+    }
+    if (notIgnored.length === 0 && issues.length === 0) {
+      writeLine("");
+      writeLine(green(bold("  \u2705 All .env files are properly protected")));
+    }
+    writeLine("");
+    return notIgnored.length > 0 ? 1 : 0;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    writeError(red(`  Protection check error: ${msg}`));
+    return 1;
+  }
+}
+async function checkProtectionJson(baseDir) {
+  const gitignorePath = join(baseDir, ".gitignore");
+  const gitignoreExists = await exists(gitignorePath);
+  let content = "";
+  let issues = [];
+  if (gitignoreExists) {
+    content = await readFile(gitignorePath);
+  }
+  for (const pattern of PROTECTED_PATTERNS) {
+    if (!content.includes(pattern)) {
+      issues.push(pattern);
+    }
+  }
+  writeJson({
+    protected: issues.length === 0,
+    gitignoreExists,
+    missingPatterns: issues
+  });
+  return issues.length === 0 ? 0 : 1;
+}
+export {
+  run
+};

package/dist/scan-TRLY36TT.js

@@ -0,0 +1,58 @@
+import {
+  formatScanResult,
+  scan
+} from "./chunk-MSXMESFP.js";
+import "./chunk-R7PZRSZ7.js";
+import "./chunk-TE7HPLA6.js";
+import {
+  bold,
+  red
+} from "./chunk-OMAOROL4.js";
+import {
+  writeError,
+  writeLine
+} from "./chunk-YN2KGTCB.js";
+
+// src/cli/commands/scan.ts
+import { resolve } from "path";
+async function run(args, ctx) {
+  try {
+    const cwd = args.flags["--cwd"] ?? ctx.cwd;
+    const baseDir = resolve(cwd);
+    const scope = args.flags["--scope"] ?? "files";
+    const outputFormat = args.flags["--format"] ?? (ctx.outputFormat === "json" ? "json" : "terminal");
+    const include = args.flags["--include"];
+    const exclude = args.flags["--exclude"];
+    const scanOptions = {
+      cwd: baseDir,
+      paths: args.positional.length > 0 ? args.positional : void 0,
+      include: include ? [include] : void 0,
+      exclude: exclude ? [exclude] : void 0,
+      scanGitHistory: scope === "git-history" || scope === "all",
+      scanStaged: scope === "staged",
+      diffFrom: scope === "diff" ? args.flags["--from"] ?? "HEAD" : void 0,
+      diffTo: scope === "diff" ? args.flags["--to"] : void 0,
+      failFast: args.flags["--fail-fast"] ?? false,
+      outputFormat
+    };
+    writeLine(bold("\u{1F510} Scanning for secrets..."));
+    writeLine("");
+    const result = await scan(scanOptions);
+    const formatted = formatScanResult(result, outputFormat);
+    process.stdout.write(formatted + "\n");
+    if (result.found) {
+      writeLine("");
+      writeError(red(bold(`  Found ${result.secrets.length} potential secret(s)!`)));
+      writeLine("");
+      return 1;
+    }
+    return 0;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    writeError(red(`  Scan error: ${msg}`));
+    return 1;
+  }
+}
+export {
+  run
+};