morphix-env 0.1.0

package/README.md

@@ -0,0 +1,272 @@
+# mx-env
+
+Environment variable toolkit for multi-project architectures. Combines [Infisical](https://infisical.com) secret management with local override files and client-side runtime injection.
+
+## Why
+
+| Problem | Solution |
+|---------|----------|
+| `NEXT_PUBLIC_*` / `VITE_*` baked at build time | `mx-env generate` creates `__env.js` for runtime injection |
+| Scattered env vars across hosting platforms | Single source of truth in Infisical, pulled at startup |
+| No local override when using remote config | `.env.local` always wins — edit one file, restart |
+| Different tools for different needs (dotenv, cross-env, infisical CLI) | One tool, one command |
+
+## Install
+
+```bash
+pnpm add -D mx-env
+# or
+npm install -D mx-env
+```
+
+## Quick Start
+
+```bash
+# Run a command with .env.local overrides
+mx-env run -- next dev
+
+# Generate client-side __env.js
+mx-env generate --out public/__env.js
+
+# Debug: see what's loaded
+mx-env inspect
+```
+
+## Commands
+
+### `mx-env run [options] -- <command>`
+
+Load environment variables, then execute a command. The child process inherits all injected vars.
+
+```bash
+# Basic: load .env.local, run dev server
+mx-env run -- next dev --turbo -p 3004
+
+# Custom env file
+mx-env run -f .env.staging -- npm start
+
+# Skip Infisical (use only local files)
+mx-env run --no-infisical -- npm start
+
+# Verbose: show which vars were loaded
+mx-env run -v -- node server.js
+```
+
+**Loading priority (high to low):**
+
+1. `.env.local` (or `--env-file`) — always wins
+2. Infisical secrets — pulled via SDK
+3. Existing `process.env` — Docker ENV, CI vars, etc.
+
+### `mx-env generate [options]`
+
+Extract public environment variables (`NEXT_PUBLIC_*`, `VITE_*`, `EXPO_PUBLIC_*`) and write them to a JS file for browser runtime injection.
+
+```bash
+# Default: public/__env.js
+mx-env generate
+
+# Custom output path (Vite projects)
+mx-env generate --out dist/__env.js
+
+# Only include specific prefix
+mx-env generate --filter NEXT_PUBLIC_
+```
+
+Output file content:
+
+```js
+window.__ENV={"NEXT_PUBLIC_API_URL":"https://api.example.com","NEXT_PUBLIC_APP_NAME":"MyApp"};
+```
+
+Load it in your HTML before your app bundle:
+
+```html
+<script src="/__env.js"></script>
+```
+
+Read in your app:
+
+```ts
+function getEnv(key: string, fallback = ''): string {
+  if (typeof window === 'undefined') return process.env[key] || fallback
+  return window.__ENV?.[key] || process.env[key] || fallback
+}
+```
+
+### `mx-env inspect [options]`
+
+Print env var values for debugging. Secrets are masked (first 4 chars shown).
+
+```bash
+mx-env inspect
+mx-env inspect --filter NEXT_PUBLIC_
+mx-env inspect -f .env.production
+```
+
+## Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--env-file <path>` | `-f` | Env file to load (default: `.env.local`, repeatable) |
+| `--out <path>` | `-o` | Output path for generate (default: `public/__env.js`) |
+| `--filter <prefix>` | | Only include vars with this prefix |
+| `--no-infisical` | | Skip Infisical SDK fetch |
+| `--verbose` | `-v` | Show loaded variable names |
+
+## Config File
+
+Create `mx-env.config.json` in your project root to declare project-level settings. This file is committed to git.
+
+```json
+{
+  "infisical": {
+    "projectId": "your-project-id",
+    "paths": ["/ai/shared", "/ai/web"],
+    "env": "$DEPLOY_ENV"
+  },
+  "envFiles": [".env.local"],
+  "generate": {
+    "out": "public/__env.js",
+    "filter": "NEXT_PUBLIC_"
+  }
+}
+```
+
+| Field | Description | Committed to git? |
+|-------|-------------|-------------------|
+| `infisical.projectId` | Infisical project ID | Yes — not a secret |
+| `infisical.paths` | Secret paths to pull | Yes — not a secret |
+| `infisical.env` | Environment name, supports `$VAR` references | Yes |
+| `envFiles` | Local override files to load | Yes |
+| `generate` | Client-side __env.js output config | Yes |
+
+**Infisical authentication** is always via environment variables — never in the config file:
+
+| Env Var | Description |
+|---------|-------------|
+| `INFISICAL_CLIENT_ID` | Machine Identity client ID |
+| `INFISICAL_CLIENT_SECRET` | Machine Identity client secret |
+| `DEPLOY_ENV` | Environment name (`dev` / `staging` / `prod`) |
+
+## Usage Examples
+
+### Next.js
+
+```json
+{
+  "scripts": {
+    "dev": "mx-env run -- next dev --turbo -p 3004",
+    "build": "mx-env run -- next build",
+    "start": "mx-env run -- node server.js"
+  }
+}
+```
+
+`mx-env.config.json`:
+
+```json
+{
+  "infisical": {
+    "projectId": "xxx",
+    "paths": ["/ai/shared", "/ai/web"],
+    "env": "$DEPLOY_ENV"
+  },
+  "envFiles": [".env.local"],
+  "generate": {
+    "out": "public/__env.js",
+    "filter": "NEXT_PUBLIC_"
+  }
+}
+```
+
+### Vite (React / Vue / Ionic)
+
+```json
+{
+  "scripts": {
+    "dev": "mx-env run -- vite",
+    "build": "mx-env run -- vite build"
+  }
+}
+```
+
+```json
+{
+  "infisical": {
+    "projectId": "xxx",
+    "paths": ["/ai/shared", "/ai/shell"],
+    "env": "$DEPLOY_ENV"
+  },
+  "generate": {
+    "out": "dist/__env.js",
+    "filter": "VITE_"
+  }
+}
+```
+
+### Express API
+
+```json
+{
+  "scripts": {
+    "dev": "mx-env run -- tsx watch src/index.ts",
+    "start": "mx-env run -- node dist/index.js"
+  }
+}
+```
+
+```json
+{
+  "infisical": {
+    "projectId": "xxx",
+    "paths": ["/ai/shared", "/ai/api"],
+    "env": "$DEPLOY_ENV"
+  }
+}
+```
+
+No `generate` field — server-side apps don't need `__env.js`.
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+RUN pnpm install && pnpm build
+
+# Only these 3 vars needed at runtime
+ENV INFISICAL_CLIENT_ID=""
+ENV INFISICAL_CLIENT_SECRET=""
+ENV DEPLOY_ENV="prod"
+
+CMD ["npx", "mx-env", "run", "--", "node", "server.js"]
+```
+
+No Infisical CLI binary needed in the image.
+
+### Local Development with Infisical CLI
+
+If you already use `infisical run` locally, mx-env still adds value as the override layer:
+
+```json
+{
+  "dev": "infisical run --path=/ai --env=dev -- mx-env run -- next dev",
+  "dev:local": "infisical run --path=/ai --env=dev -- mx-env run -- next dev"
+}
+```
+
+`.env.local` overrides take effect on top of Infisical CLI injection.
+
+## How It Works
+
+1. Read `mx-env.config.json` for project settings
+2. If `INFISICAL_CLIENT_ID` + `INFISICAL_CLIENT_SECRET` exist → fetch secrets via SDK, inject into `process.env` (does not overwrite existing vars)
+3. Read `.env.local` → inject into `process.env` (overwrites everything, highest priority)
+4. If `generate` is configured → write `__env.js` with public vars
+5. Spawn child command — it inherits the fully assembled `process.env`
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/env.ts
+var import_fs = require("fs");
+var import_path = require("path");
+function parseEnvFile(filePath) {
+  const absPath = (0, import_path.resolve)(filePath);
+  if (!(0, import_fs.existsSync)(absPath)) return {};
+  const vars = {};
+  const content = (0, import_fs.readFileSync)(absPath, "utf8");
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return vars;
+}
+function loadEnvFiles(files) {
+  const overrides = [];
+  for (const file of files) {
+    const vars = parseEnvFile(file);
+    for (const [key, value] of Object.entries(vars)) {
+      process.env[key] = value;
+      overrides.push({ key, source: file });
+    }
+  }
+  return overrides;
+}
+var PUBLIC_PREFIXES = ["NEXT_PUBLIC_", "VITE_", "EXPO_PUBLIC_"];
+function extractPublicVars() {
+  const vars = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value && PUBLIC_PREFIXES.some((p) => key.startsWith(p))) {
+      vars[key] = value;
+    }
+  }
+  return vars;
+}
+
+// src/infisical.ts
+var import_sdk = require("@infisical/sdk");
+function getInfisicalConfig() {
+  const clientId = process.env.INFISICAL_CLIENT_ID;
+  const clientSecret = process.env.INFISICAL_CLIENT_SECRET;
+  const projectId = process.env.INFISICAL_PROJECT_ID;
+  if (!clientId || !clientSecret || !projectId) return null;
+  return {
+    clientId,
+    clientSecret,
+    projectId,
+    environment: process.env.DEPLOY_ENV || process.env.INFISICAL_ENV || "dev",
+    paths: (process.env.INFISICAL_PATHS || "/").split(",").map((p) => p.trim()),
+    siteUrl: process.env.INFISICAL_SITE_URL
+  };
+}
+async function fetchInfisicalSecrets(config) {
+  const client = new import_sdk.InfisicalSDK({
+    ...config.siteUrl ? { siteUrl: config.siteUrl } : {}
+  });
+  await client.auth().universalAuth.login({
+    clientId: config.clientId,
+    clientSecret: config.clientSecret
+  });
+  let count = 0;
+  for (const secretPath of config.paths) {
+    const result = await client.secrets().listSecrets({
+      environment: config.environment,
+      projectId: config.projectId,
+      secretPath,
+      expandSecretReferences: true,
+      viewSecretValue: true
+    });
+    for (const secret of result.secrets) {
+      process.env[secret.secretKey] = secret.secretValue;
+      count++;
+    }
+  }
+  return count;
+}
+
+// src/config.ts
+var import_fs2 = require("fs");
+var import_path2 = require("path");
+var CONFIG_FILE = "mx-env.config.json";
+function resolveEnvRef(value) {
+  if (value.startsWith("$")) {
+    return process.env[value.slice(1)] || "";
+  }
+  return value;
+}
+function loadConfig() {
+  const configPath = (0, import_path2.resolve)(CONFIG_FILE);
+  if (!(0, import_fs2.existsSync)(configPath)) return {};
+  try {
+    const raw = JSON.parse((0, import_fs2.readFileSync)(configPath, "utf8"));
+    if (raw.infisical?.env) {
+      raw.infisical.env = resolveEnvRef(raw.infisical.env);
+    }
+    return raw;
+  } catch (e) {
+    console.warn(`[mx-env] Failed to parse ${CONFIG_FILE}: ${e.message}`);
+    return {};
+  }
+}
+
+// src/cli.ts
+var import_cross_spawn = __toESM(require("cross-spawn"));
+var import_fs3 = require("fs");
+var import_path3 = require("path");
+var VERSION = "0.1.0";
+var DEFAULT_ENV_FILE = ".env.local";
+function parseArgs(argv) {
+  const args = {
+    command: "",
+    subArgs: [],
+    envFiles: [],
+    outFile: null,
+    verbose: false,
+    filter: null,
+    noInfisical: false
+  };
+  let i = 2;
+  const command = argv[i];
+  if (!command) return args;
+  args.command = command;
+  i++;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--") {
+      args.subArgs = argv.slice(i + 1);
+      break;
+    }
+    if (arg === "--env-file" || arg === "-f") {
+      i++;
+      if (argv[i]) args.envFiles.push(argv[i]);
+    } else if (arg === "--out" || arg === "-o") {
+      i++;
+      if (argv[i]) args.outFile = argv[i];
+    } else if (arg === "--filter") {
+      i++;
+      if (argv[i]) args.filter = argv[i];
+    } else if (arg === "--verbose" || arg === "-v") {
+      args.verbose = true;
+    } else if (arg === "--no-infisical") {
+      args.noInfisical = true;
+    } else {
+      if (args.command === "run") {
+        args.subArgs = argv.slice(i);
+        break;
+      }
+    }
+    i++;
+  }
+  return args;
+}
+function mergeWithConfig(args, config) {
+  if (args.envFiles.length === 0) {
+    args.envFiles = config.envFiles || [DEFAULT_ENV_FILE];
+  }
+  if (!args.outFile && config.generate) {
+    args.outFile = config.generate.out;
+  }
+  if (!args.filter && config.generate?.filter) {
+    args.filter = config.generate.filter;
+  }
+  return args;
+}
+async function loadAllEnv(args, config) {
+  if (!args.noInfisical) {
+    const infisicalConfig = config.infisical ? {
+      clientId: process.env.INFISICAL_CLIENT_ID || "",
+      clientSecret: process.env.INFISICAL_CLIENT_SECRET || "",
+      projectId: config.infisical.projectId,
+      environment: config.infisical.env || "dev",
+      paths: config.infisical.paths || ["/"],
+      siteUrl: config.infisical.siteUrl
+    } : getInfisicalConfig();
+    if (infisicalConfig && infisicalConfig.clientId && infisicalConfig.clientSecret) {
+      try {
+        const count = await fetchInfisicalSecrets(infisicalConfig);
+        console.log(`[mx-env] Infisical: loaded ${count} secrets (${infisicalConfig.environment}: ${infisicalConfig.paths.join(", ")})`);
+      } catch (e) {
+        console.warn(`[mx-env] Infisical: failed - ${e.message}`);
+      }
+    } else if (args.verbose) {
+      console.log("[mx-env] Infisical: skipped (no credentials)");
+    }
+  }
+  const overrides = loadEnvFiles(args.envFiles);
+  if (overrides.length > 0) {
+    console.log(`[mx-env] Loaded ${overrides.length} overrides from ${args.envFiles.join(", ")}`);
+    if (args.verbose) {
+      for (const o of overrides) {
+        console.log(`  ${o.key} (from ${o.source})`);
+      }
+    }
+  }
+}
+async function cmdRun(args, config) {
+  if (args.subArgs.length === 0) {
+    console.error("[mx-env] No command specified. Usage: mx-env run -- <command>");
+    process.exit(1);
+  }
+  await loadAllEnv(args, config);
+  if (args.outFile) {
+    generateClientEnv(args.outFile, args.filter);
+  }
+  const [cmd, ...cmdArgs] = args.subArgs;
+  const result = import_cross_spawn.default.sync(cmd, cmdArgs, {
+    stdio: "inherit",
+    env: process.env
+  });
+  if (result.error) {
+    console.error(`[mx-env] Failed to execute: ${cmd}`, result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}
+function generateClientEnv(outFile, filter) {
+  let vars = extractPublicVars();
+  if (filter) {
+    vars = Object.fromEntries(
+      Object.entries(vars).filter(([key]) => key.startsWith(filter))
+    );
+  }
+  const js = `window.__ENV=${JSON.stringify(vars)};`;
+  (0, import_fs3.mkdirSync)((0, import_path3.dirname)(outFile), { recursive: true });
+  (0, import_fs3.writeFileSync)(outFile, js);
+  console.log(`[mx-env] Generated ${outFile} (${Object.keys(vars).length} client vars)`);
+}
+async function cmdGenerate(args, config) {
+  const outFile = args.outFile || "public/__env.js";
+  await loadAllEnv(args, config);
+  generateClientEnv(outFile, args.filter);
+  if (args.verbose) {
+    const vars = extractPublicVars();
+    for (const key of Object.keys(vars)) {
+      console.log(`  ${key}`);
+    }
+  }
+}
+function cmdInspect(args) {
+  for (const file of args.envFiles.length > 0 ? args.envFiles : [DEFAULT_ENV_FILE]) {
+    const vars = parseEnvFile(file);
+    const keys = Object.keys(vars);
+    if (keys.length === 0) {
+      console.log(`${file}: (not found or empty)`);
+      continue;
+    }
+    console.log(`${file}: (${keys.length} vars)`);
+    for (const [key, value] of Object.entries(vars)) {
+      if (args.filter && !key.startsWith(args.filter)) continue;
+      const display = value.length > 8 ? value.slice(0, 4) + "***" : value;
+      console.log(`  ${key}=${display}`);
+    }
+  }
+  const publicVars = extractPublicVars();
+  const filtered = args.filter ? Object.entries(publicVars).filter(([k]) => k.startsWith(args.filter)) : Object.entries(publicVars);
+  if (filtered.length > 0) {
+    console.log(`
+process.env public vars: (${filtered.length})`);
+    for (const [key, value] of filtered) {
+      const display = value.length > 8 ? value.slice(0, 4) + "***" : value;
+      console.log(`  ${key}=${display}`);
+    }
+  }
+}
+function showHelp() {
+  console.log(`
+mx-env v${VERSION} \u2014 MorphixAI environment variable toolkit
+
+Usage:
+  mx-env run [options] -- <command>     Load env + exec command
+  mx-env generate [options]             Generate __env.js for client-side runtime
+  mx-env inspect [options]              Print env vars for debugging
+
+Options:
+  -f, --env-file <path>    Env file to load (default: .env.local, repeatable)
+  -o, --out <path>         Output path for generate (default: public/__env.js)
+  --filter <prefix>        Only include vars with this prefix
+  --no-infisical           Skip Infisical SDK fetch
+  -v, --verbose            Show loaded variable names
+  --help, -h               Show this help
+  --version                Show version
+
+Config file (mx-env.config.json):
+  {
+    "infisical": {
+      "projectId": "xxx",
+      "paths": ["/ai/shared", "/ai/web"],
+      "env": "$DEPLOY_ENV"
+    },
+    "envFiles": [".env.local"],
+    "generate": {
+      "out": "public/__env.js",
+      "filter": "NEXT_PUBLIC_"
+    }
+  }
+
+Env loading priority (high \u2192 low):
+  1. .env.local (or --env-file)
+  2. Infisical secrets
+  3. Existing process.env
+
+Examples:
+  mx-env run -- next dev --turbo -p 3004
+  mx-env run --no-infisical -- npm start
+  mx-env run -f .env.staging -- npm start
+  mx-env generate --out dist/__env.js
+  mx-env inspect --filter VITE_
+`);
+}
+async function main() {
+  const config = loadConfig();
+  const args = mergeWithConfig(parseArgs(process.argv), config);
+  switch (args.command) {
+    case "run":
+      await cmdRun(args, config);
+      break;
+    case "generate":
+    case "gen":
+      await cmdGenerate(args, config);
+      break;
+    case "inspect":
+      cmdInspect(args);
+      break;
+    case "--help":
+    case "-h":
+    case "help":
+      showHelp();
+      break;
+    case "--version":
+      console.log(VERSION);
+      break;
+    default:
+      if (args.command) {
+        console.error(`[mx-env] Unknown command: ${args.command}`);
+      }
+      showHelp();
+      process.exit(args.command ? 1 : 0);
+  }
+}
+main().catch((e) => {
+  console.error("[mx-env] Fatal:", e.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "morphix-env",
+  "version": "0.1.0",
+  "description": "Environment variable toolkit — Infisical integration, local overrides, and client-side runtime injection for Next.js / Vite / Express.",
+  "author": "MorphixAI <dev@morphixai.com>",
+  "homepage": "https://github.com/Morphicai/mx-env#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Morphicai/mx-env.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Morphicai/mx-env/issues"
+  },
+  "bin": {
+    "morphix-env": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format cjs --dts --clean",
+    "dev": "tsup src/cli.ts --format cjs --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "env",
+    "dotenv",
+    "environment-variables",
+    "cross-env",
+    "infisical",
+    "secrets",
+    "runtime-env",
+    "nextjs",
+    "vite",
+    "docker",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.1"
+  },
+  "dependencies": {
+    "@infisical/sdk": "^5.0.0",
+    "cross-spawn": "^7.0.6"
+  }
+}