ultraenv 1.0.0

package/dist/init-Y7JQ2KYJ.js

@@ -0,0 +1,146 @@
+import {
+  confirm,
+  prompt
+} from "./chunk-YTICOB5M.js";
+import {
+  bold,
+  cyan,
+  green,
+  red
+} from "./chunk-OMAOROL4.js";
+import {
+  writeError,
+  writeLine
+} from "./chunk-YN2KGTCB.js";
+import {
+  exists,
+  writeFile
+} from "./chunk-3VYXPTYV.js";
+import {
+  DEFAULT_GITIGNORE_ENTRIES
+} from "./chunk-XC65ORJ5.js";
+import {
+  FileSystemError,
+  getErrorMessage
+} from "./chunk-5G2DU52U.js";
+
+// src/cli/commands/init.ts
+import { resolve, join } from "path";
+var DEFAULT_ENV_CONTENT = `# Environment Variables
+# Created by ultraenv \u2014 https://github.com/Avinashvelu03/ultraenv
+
+# App
+NODE_ENV=development
+APP_NAME=
+APP_URL=http://localhost:3000
+
+# Database
+DATABASE_URL=
+DATABASE_POOL_SIZE=10
+
+# Server
+PORT=3000
+HOST=localhost
+
+# Logging
+LOG_LEVEL=info
+`;
+async function run(args, ctx) {
+  try {
+    const cwd = args.flags["--cwd"] ?? ctx.cwd;
+    const baseDir = resolve(cwd);
+    writeLine(bold("\u{1F680} ultraenv project initialization"));
+    writeLine("");
+    const configPath = join(baseDir, ".ultraenvrc.json");
+    const envPath = join(baseDir, ".env");
+    if (await exists(configPath) && !args.flags["--force"]) {
+      writeLine(cyan("  An ultraenv configuration already exists."));
+      const overwrite = await confirm("  Overwrite existing configuration?", false);
+      if (!overwrite) {
+        writeLine(green("  Initialization cancelled."));
+        return 0;
+      }
+    }
+    await prompt("  Project name", { default: baseDir.split("/").pop() ?? "my-project" });
+    const envDir = await prompt("  Environment directory", { default: "." });
+    writeLine("");
+    writeLine(cyan("  Creating configuration..."));
+    const configContent = JSON.stringify({
+      envDir,
+      expandVariables: true,
+      overrideProcessEnv: false,
+      mergeStrategy: "last-wins",
+      outputFormat: "terminal",
+      debug: false
+    }, null, 2) + "\n";
+    await writeFile(configPath, configContent);
+    writeLine(green(`  \u2713 Created ${configPath}`));
+    if (!await exists(envPath)) {
+      writeLine(cyan("  Creating .env file..."));
+      await writeFile(envPath, DEFAULT_ENV_CONTENT);
+      writeLine(green(`  \u2713 Created ${envPath}`));
+    } else {
+      writeLine(cyan(`  .env already exists, skipping.`));
+    }
+    const examplePath = join(baseDir, ".env.example");
+    if (!await exists(examplePath)) {
+      const exampleContent = `# Environment Variables Template
+# Auto-generated by ultraenv
+# Copy this file to .env and fill in the values
+
+# App
+NODE_ENV=development
+APP_NAME=<your-app-name>
+APP_URL=http://localhost:3000
+
+# Database
+DATABASE_URL=<your-database-url>
+DATABASE_POOL_SIZE=10
+
+# Server
+PORT=3000
+HOST=localhost
+
+# Logging
+LOG_LEVEL=info
+`;
+      await writeFile(examplePath, exampleContent);
+      writeLine(green(`  \u2713 Created ${examplePath}`));
+    }
+    const gitignorePath = join(baseDir, ".gitignore");
+    if (await exists(gitignorePath)) {
+      const { readFile } = await import("./fs-VH7ATUS3.js");
+      const existingContent = await readFile(gitignorePath);
+      if (!existingContent.includes("# ultraenv")) {
+        const { appendFileSync } = await import("fs");
+        appendFileSync(gitignorePath, "\n" + DEFAULT_GITIGNORE_ENTRIES.join("\n") + "\n");
+        writeLine(green("  \u2713 Updated .gitignore"));
+      } else {
+        writeLine(cyan("  .gitignore already contains ultraenv entries"));
+      }
+    } else {
+      const gitignoreContent = DEFAULT_GITIGNORE_ENTRIES.join("\n") + "\n";
+      await writeFile(gitignorePath, gitignoreContent);
+      writeLine(green("  \u2713 Created .gitignore"));
+    }
+    writeLine("");
+    writeLine(green(bold("  \u2705 ultraenv initialized successfully!")));
+    writeLine("");
+    writeLine(cyan("  Next steps:"));
+    writeLine(`    1. Edit ${envPath} with your environment variables`);
+    writeLine(`    2. Edit ${configPath} to customize settings`);
+    writeLine(`    3. Run ${cyan("ultraenv validate")} to check your configuration`);
+    writeLine("");
+    return 0;
+  } catch (error) {
+    if (error instanceof FileSystemError) {
+      writeError(red(`  Error: ${getErrorMessage(error)}`));
+      return 1;
+    }
+    writeError(red(`  Error: ${error instanceof Error ? error.message : String(error)}`));
+    return 1;
+  }
+}
+export {
+  run
+};

package/dist/install-hook-SKXIV6NV.js

@@ -0,0 +1,111 @@
+import {
+  isGitRepository
+} from "./chunk-R7PZRSZ7.js";
+import {
+  bold,
+  cyan,
+  green,
+  red,
+  yellow
+} from "./chunk-OMAOROL4.js";
+import {
+  writeError,
+  writeLine
+} from "./chunk-YN2KGTCB.js";
+import {
+  ensureDir,
+  exists,
+  writeFile
+} from "./chunk-3VYXPTYV.js";
+import "./chunk-5G2DU52U.js";
+
+// src/cli/commands/install-hook.ts
+import { resolve, join } from "path";
+var HOOK_SCRIPT = `#!/bin/sh
+# ultraenv pre-commit hook
+# Validates environment, checks sync, and scans for secrets
+
+echo "Running ultraenv pre-commit checks..."
+
+# Check if ultraenv is available
+if ! command -v ultraenv >/dev/null 2>&1; then
+  echo "Warning: ultraenv not found. Skipping pre-commit checks."
+  echo "Install with: npm install -g ultraenv"
+  exit 0
+fi
+
+# Validate environment
+echo "  \u2192 Validating environment..."
+ultraenv ci validate --format json --strict
+if [ $? -ne 0 ]; then
+  echo "\u2717 Environment validation failed"
+  exit 1
+fi
+
+# Check sync
+echo "  \u2192 Checking .env sync..."
+ultraenv ci check-sync
+if [ $? -ne 0 ]; then
+  echo "\u26A0 .env.example is out of sync (non-blocking)"
+fi
+
+# Scan for secrets
+echo "  \u2192 Scanning for secrets..."
+ultraenv ci scan --format sarif --output .ultraenv-scan.sarif
+if [ $? -ne 0 ]; then
+  echo "\u2717 Secret scan detected potential secrets!"
+  echo "  Review the findings and remove any committed secrets."
+  exit 1
+fi
+
+echo "\u2713 All pre-commit checks passed"
+exit 0
+`;
+async function run(args, ctx) {
+  try {
+    const cwd = args.flags["--cwd"] ?? ctx.cwd;
+    const baseDir = resolve(cwd);
+    const isGit = await isGitRepository(baseDir);
+    if (!isGit) {
+      writeError(red("  Not a git repository. Cannot install hooks."));
+      return 1;
+    }
+    const { getGitRoot } = await import("./git-BZS4DPAI.js");
+    const gitRoot = await getGitRoot(baseDir);
+    if (!gitRoot) {
+      writeError(red("  Could not determine git root."));
+      return 1;
+    }
+    const hooksDir = join(gitRoot, ".git", "hooks");
+    const hookPath = join(hooksDir, "pre-commit");
+    if (await exists(hookPath) && !args.flags["--force"]) {
+      writeLine(yellow("  A pre-commit hook already exists."));
+      writeLine(yellow(`  Path: ${hookPath}`));
+      writeLine(yellow("  Use --force to overwrite."));
+      return 0;
+    }
+    await ensureDir(hooksDir);
+    await writeFile(hookPath, HOOK_SCRIPT);
+    const { chmodSync } = await import("fs");
+    chmodSync(hookPath, 493);
+    writeLine(green(bold("  \u2705 Pre-commit hook installed!")));
+    writeLine("");
+    writeLine(cyan(`  Hook path: ${hookPath}`));
+    writeLine("");
+    writeLine(cyan("  The hook will run on every commit and:"));
+    writeLine("    \u2713 Validate environment variables");
+    writeLine("    \u2713 Check .env \u2194 .env.example sync");
+    writeLine("    \u2713 Scan for leaked secrets");
+    writeLine("");
+    writeLine(yellow("  Bypass with: git commit --no-verify"));
+    writeLine("");
+    return 0;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    writeError(red(`  Error: ${msg}`));
+    return 1;
+  }
+}
+export {
+  run
+};

package/dist/json-schema-I26YNQBH.js

@@ -0,0 +1,10 @@
+import {
+  generateJsonSchema,
+  generateJsonSchemaContent
+} from "./chunk-6KS56D6E.js";
+import "./chunk-3VYXPTYV.js";
+import "./chunk-5G2DU52U.js";
+export {
+  generateJsonSchema,
+  generateJsonSchemaContent
+};

package/dist/key-manager-O3G55WPU.js

@@ -0,0 +1,25 @@
+import {
+  deriveEnvironmentKey,
+  formatKey,
+  generateKeysFile,
+  generateMasterKey,
+  isValidKeyFormat,
+  maskKey,
+  parseKey,
+  parseKeysFile,
+  rotateKey
+} from "./chunk-UEWYFN6A.js";
+import "./chunk-2USZPWLZ.js";
+import "./chunk-XC65ORJ5.js";
+import "./chunk-5G2DU52U.js";
+export {
+  deriveEnvironmentKey,
+  formatKey,
+  generateKeysFile,
+  generateMasterKey,
+  isValidKeyFormat,
+  maskKey,
+  parseKey,
+  parseKeysFile,
+  rotateKey
+};

package/dist/middleware/express.cjs

@@ -0,0 +1,103 @@
+"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/express.ts
+var express_exports = {};
+__export(express_exports, {
+  healthCheckRoute: () => healthCheckRoute,
+  ultraenvMiddleware: () => ultraenvMiddleware
+});
+module.exports = __toCommonJS(express_exports);
+function ultraenvMiddleware(options = {}) {
+  const {
+    exposePublic = true,
+    prefix = "PUBLIC_",
+    additionalPrefixes = [],
+    allowList = [],
+    denyList = [],
+    exposeNodeEnv = true,
+    source = process.env
+  } = options;
+  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 = buildFilteredEnv(
+    source,
+    allPrefixes,
+    allowSet,
+    denySet,
+    exposePublic,
+    exposeNodeEnv
+  );
+  return (_req, _res, next) => {
+    _req.env = filteredEnv;
+    next();
+  };
+}
+function buildFilteredEnv(source, prefixes, allowSet, denySet, exposePublic, exposeNodeEnv) {
+  if (!exposePublic) {
+    return {};
+  }
+  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 healthCheckRoute(options = {}) {
+  const { source = process.env, metadata = {} } = options;
+  return (_req, res) => {
+    const envKeys = Object.keys(source).filter(
+      (k) => source[k] !== void 0 && source[k] !== ""
+    );
+    const nodeEnv = source["NODE_ENV"] ?? "unknown";
+    const response = {
+      status: "ok",
+      loaded: envKeys.length,
+      environment: nodeEnv,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
+    };
+    res.status(200).json(response);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  healthCheckRoute,
+  ultraenvMiddleware
+});

package/dist/middleware/express.d.cts

@@ -0,0 +1,115 @@
+/** Minimal Express Request type */
+interface UltraenvRequest {
+    [key: string]: unknown;
+    env?: UltraenvFilteredEnv;
+}
+/** Minimal Express Response type */
+interface UltraenvResponse {
+    status(code: number): UltraenvResponse;
+    json(data: Record<string, unknown>): void;
+}
+/** Express NextFunction type */
+type UltraenvNextFunction = (err?: Error) => void;
+/** Options for the ultraenv Express middleware */
+interface UltraenvMiddlewareOptions {
+    /**
+     * Whether to expose public env vars.
+     * When true, filters process.env by the specified prefix and attaches
+     * a filtered subset to req.env.
+     * Default: true
+     */
+    exposePublic?: boolean;
+    /**
+     * Prefix to filter public variables by.
+     * Only env vars starting with this prefix will be included in req.env.
+     * Default: 'PUBLIC_'
+     */
+    prefix?: string;
+    /**
+     * Additional prefixes to include in the filtered env.
+     * Useful for framework-specific prefixes (e.g., ['NEXT_PUBLIC_', 'VITE_']).
+     * Default: []
+     */
+    additionalPrefixes?: readonly string[];
+    /**
+     * Explicit list of env var names to always include.
+     * These are included regardless of prefix matching.
+     * Default: []
+     */
+    allowList?: readonly string[];
+    /**
+     * Explicit list of env var names to always exclude.
+     * Even if they match the prefix, they will be excluded.
+     * Default: []
+     */
+    denyList?: readonly string[];
+    /**
+     * Whether to also set NODE_ENV on req.env.
+     * Default: true
+     */
+    exposeNodeEnv?: boolean;
+    /**
+     * Custom source for environment variables.
+     * Defaults to process.env if not provided.
+     */
+    source?: Record<string, string | undefined>;
+}
+/** The filtered env object attached to req.env */
+interface UltraenvFilteredEnv {
+    /** The filtered environment variables */
+    [key: string]: string;
+}
+/**
+ * Create an Express/Connect middleware that filters environment variables
+ * by prefix and attaches them to `req.env`.
+ *
+ * Only env vars matching the specified prefix(es) are included,
+ * preventing accidental exposure of secrets to client-side code.
+ *
+ * @param options - Middleware configuration options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { ultraenvMiddleware } from 'ultraenv/middleware';
+ *
+ * const app = express();
+ * app.use(ultraenvMiddleware({
+ *   exposePublic: true,
+ *   prefix: 'PUBLIC_',
+ *   additionalPrefixes: ['NEXT_PUBLIC_', 'VITE_'],
+ * }));
+ *
+ * // Now in routes:
+ * app.get('/api/config', (req, res) => {
+ *   res.json({
+ *     apiUrl: req.env?.PUBLIC_API_URL,
+ *     siteUrl: req.env?.PUBLIC_SITE_URL,
+ *   });
+ * });
+ * ```
+ */
+declare function ultraenvMiddleware(options?: UltraenvMiddlewareOptions): (req: UltraenvRequest, res: UltraenvResponse, next: UltraenvNextFunction) => void;
+/**
+ * Create a health check route handler that returns env health status.
+ * Does NOT expose secret values — only counts and metadata.
+ *
+ * @param options - Health check options
+ * @returns Express route handler
+ *
+ * @example
+ * ```typescript
+ * import { healthCheckRoute } from 'ultraenv/middleware';
+ * app.get('/health/env', healthCheckRoute());
+ * // Response: { status: 'ok', loaded: 38, environment: 'production', timestamp: '...' }
+ * ```
+ */
+declare function healthCheckRoute(options?: {
+    /** Custom env source. Defaults to process.env */
+    source?: Record<string, string | undefined>;
+    /** Additional metadata to include */
+    metadata?: Record<string, string | number | boolean>;
+}): (req: UltraenvRequest, res: UltraenvResponse) => void;
+
+export { type UltraenvFilteredEnv, type UltraenvMiddlewareOptions, type UltraenvNextFunction, type UltraenvRequest, type UltraenvResponse, healthCheckRoute, ultraenvMiddleware };

package/dist/middleware/express.d.ts

@@ -0,0 +1,115 @@
+/** Minimal Express Request type */
+interface UltraenvRequest {
+    [key: string]: unknown;
+    env?: UltraenvFilteredEnv;
+}
+/** Minimal Express Response type */
+interface UltraenvResponse {
+    status(code: number): UltraenvResponse;
+    json(data: Record<string, unknown>): void;
+}
+/** Express NextFunction type */
+type UltraenvNextFunction = (err?: Error) => void;
+/** Options for the ultraenv Express middleware */
+interface UltraenvMiddlewareOptions {
+    /**
+     * Whether to expose public env vars.
+     * When true, filters process.env by the specified prefix and attaches
+     * a filtered subset to req.env.
+     * Default: true
+     */
+    exposePublic?: boolean;
+    /**
+     * Prefix to filter public variables by.
+     * Only env vars starting with this prefix will be included in req.env.
+     * Default: 'PUBLIC_'
+     */
+    prefix?: string;
+    /**
+     * Additional prefixes to include in the filtered env.
+     * Useful for framework-specific prefixes (e.g., ['NEXT_PUBLIC_', 'VITE_']).
+     * Default: []
+     */
+    additionalPrefixes?: readonly string[];
+    /**
+     * Explicit list of env var names to always include.
+     * These are included regardless of prefix matching.
+     * Default: []
+     */
+    allowList?: readonly string[];
+    /**
+     * Explicit list of env var names to always exclude.
+     * Even if they match the prefix, they will be excluded.
+     * Default: []
+     */
+    denyList?: readonly string[];
+    /**
+     * Whether to also set NODE_ENV on req.env.
+     * Default: true
+     */
+    exposeNodeEnv?: boolean;
+    /**
+     * Custom source for environment variables.
+     * Defaults to process.env if not provided.
+     */
+    source?: Record<string, string | undefined>;
+}
+/** The filtered env object attached to req.env */
+interface UltraenvFilteredEnv {
+    /** The filtered environment variables */
+    [key: string]: string;
+}
+/**
+ * Create an Express/Connect middleware that filters environment variables
+ * by prefix and attaches them to `req.env`.
+ *
+ * Only env vars matching the specified prefix(es) are included,
+ * preventing accidental exposure of secrets to client-side code.
+ *
+ * @param options - Middleware configuration options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { ultraenvMiddleware } from 'ultraenv/middleware';
+ *
+ * const app = express();
+ * app.use(ultraenvMiddleware({
+ *   exposePublic: true,
+ *   prefix: 'PUBLIC_',
+ *   additionalPrefixes: ['NEXT_PUBLIC_', 'VITE_'],
+ * }));
+ *
+ * // Now in routes:
+ * app.get('/api/config', (req, res) => {
+ *   res.json({
+ *     apiUrl: req.env?.PUBLIC_API_URL,
+ *     siteUrl: req.env?.PUBLIC_SITE_URL,
+ *   });
+ * });
+ * ```
+ */
+declare function ultraenvMiddleware(options?: UltraenvMiddlewareOptions): (req: UltraenvRequest, res: UltraenvResponse, next: UltraenvNextFunction) => void;
+/**
+ * Create a health check route handler that returns env health status.
+ * Does NOT expose secret values — only counts and metadata.
+ *
+ * @param options - Health check options
+ * @returns Express route handler
+ *
+ * @example
+ * ```typescript
+ * import { healthCheckRoute } from 'ultraenv/middleware';
+ * app.get('/health/env', healthCheckRoute());
+ * // Response: { status: 'ok', loaded: 38, environment: 'production', timestamp: '...' }
+ * ```
+ */
+declare function healthCheckRoute(options?: {
+    /** Custom env source. Defaults to process.env */
+    source?: Record<string, string | undefined>;
+    /** Additional metadata to include */
+    metadata?: Record<string, string | number | boolean>;
+}): (req: UltraenvRequest, res: UltraenvResponse) => void;
+
+export { type UltraenvFilteredEnv, type UltraenvMiddlewareOptions, type UltraenvNextFunction, type UltraenvRequest, type UltraenvResponse, healthCheckRoute, ultraenvMiddleware };

package/dist/middleware/express.js

@@ -0,0 +1,8 @@
+import {
+  healthCheckRoute,
+  ultraenvMiddleware
+} from "../chunk-IKPTKALB.js";
+export {
+  healthCheckRoute,
+  ultraenvMiddleware
+};