envlock-core 0.2.0 → 0.4.0

package/README.md

@@ -4,30 +4,67 @@ Framework-agnostic 1Password + dotenvx secret injection logic.
 
 > Most users should install [`envlock-next`](https://www.npmjs.com/package/envlock-next) instead. This package is for integrating envlock with frameworks other than Next.js.
 
+## Prerequisites
+
+- [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) installed and signed in
+- [dotenvx](https://dotenvx.com/docs/install) installed (`npm install -g @dotenvx/dotenvx`)
+- Encrypted `.env.*` files committed to your repo (see [dotenvx quickstart](https://dotenvx.com/docs/quickstart))
+
 ## Install
 
 ```bash
 pnpm add envlock-core
 ```
 
-## API
+## Usage
 
-### `runWithSecrets(options)`
+### `envlock.config.js`
 
-Runs a command with secrets injected from 1Password via dotenvx. If `DOTENV_PRIVATE_KEY_<ENV>` is already set (e.g. in CI), it skips `op run` and calls `dotenvx run` directly.
-
-```ts
-import { runWithSecrets } from 'envlock-core';
+Create `envlock.config.js` in your project root:
 
-runWithSecrets({
-  envFile: '.env.production',
-  environment: 'production',
+```js
+// envlock.config.js
+export default {
   onePasswordEnvId: 'ca6uypwvab5mevel44gqdc2zae',
-  command: 'node',
-  args: ['server.js'],
-});
+  envFiles: {
+    development: '.env.development',
+    staging: '.env.staging',
+    production: '.env.production',
+  },
+  commands: {
+    dev:   'node server.js --watch',
+    start: 'node server.js --port 3000',
+    build: 'node build.js',
+  },
+};
 ```
 
+Then wire up your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev":   "envlock dev",
+    "build": "envlock build --production",
+    "start": "envlock start --production"
+  }
+}
+```
+
+Pass `--staging` or `--production` to switch environments. For ad-hoc commands, pass the command directly without a config key:
+
+```bash
+envlock node server.js --production
+```
+
+Set `ENVLOCK_OP_ENV_ID` to provide the 1Password Environment ID via env var instead of the config file. In CI, set `DOTENV_PRIVATE_KEY_<ENV>` directly and `op run` is skipped automatically.
+
+## API
+
+### `runWithSecrets(options)`
+
+Runs a command with secrets injected from 1Password via dotenvx. If `DOTENV_PRIVATE_KEY_<ENV>` is already set (e.g. in CI), it skips `op run` and calls `dotenvx run` directly.
+
 **Options:**
 
 | Option             | Type          | Description                                               |
@@ -65,6 +102,12 @@ const ENVIRONMENTS = {
 
 type Environment = keyof typeof ENVIRONMENTS;
 
+interface EnvlockConfig {
+  onePasswordEnvId?: string; // or set ENVLOCK_OP_ENV_ID env var
+  envFiles?: Partial<Record<Environment, string>>;
+  commands?: Record<string, string>;
+}
+
 interface EnvlockOptions {
   onePasswordEnvId: string;
   envFiles?: Partial<Record<Environment, string>>;

package/dist/cli/index.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { pathToFileURL as pathToFileURL2 } from "url";
+
+// src/types.ts
+var ENVIRONMENTS = {
+  development: "development",
+  staging: "staging",
+  production: "production"
+};
+
+// src/invoke.ts
+import { spawnSync } from "child_process";
+
+// src/detect.ts
+import { execFileSync } from "child_process";
+var WHICH = process.platform === "win32" ? "where" : "which";
+function hasBinary(name) {
+  try {
+    execFileSync(WHICH, [name], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function checkBinary(name, installHint) {
+  if (!hasBinary(name)) {
+    console.error(`[envlock] '${name}' not found in PATH.
+${installHint}`);
+    process.exit(1);
+  }
+}
+
+// src/invoke.ts
+function runWithSecrets(options) {
+  const { envFile, environment, onePasswordEnvId, command, args } = options;
+  checkBinary(
+    "dotenvx",
+    "Install dotenvx: npm install -g @dotenvx/dotenvx\nOr add it as a dev dependency."
+  );
+  const privateKeyVar = `DOTENV_PRIVATE_KEY_${environment.toUpperCase()}`;
+  const keyAlreadyInjected = !!process.env[privateKeyVar];
+  let result;
+  if (keyAlreadyInjected) {
+    result = spawnSync(
+      "dotenvx",
+      ["run", "-f", envFile, "--", command, ...args],
+      { stdio: "inherit" }
+    );
+  } else {
+    checkBinary(
+      "op",
+      "Install 1Password CLI: brew install --cask 1password-cli@beta\nThen sign in: op signin"
+    );
+    result = spawnSync(
+      "op",
+      [
+        "run",
+        "--environment",
+        onePasswordEnvId,
+        "--",
+        "dotenvx",
+        "run",
+        "-f",
+        envFile,
+        "--",
+        command,
+        ...args
+      ],
+      { stdio: "inherit" }
+    );
+  }
+  process.exit(result.status ?? 1);
+}
+
+// src/validate.ts
+import { isAbsolute, relative, resolve } from "path";
+var OP_ENV_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function validateOnePasswordEnvId(id) {
+  if (!id || !OP_ENV_ID_PATTERN.test(id)) {
+    throw new Error(
+      `[envlock] Invalid onePasswordEnvId: "${id}". Must be a lowercase alphanumeric string (hyphens allowed), e.g. 'ca6uypwvab5mevel44gqdc2zae'.`
+    );
+  }
+}
+function validateEnvFilePath(envFile, cwd) {
+  if (envFile.includes("\0")) {
+    throw new Error(`[envlock] Invalid env file path: null bytes are not allowed.`);
+  }
+  const resolved = resolve(cwd, envFile);
+  const base = resolve(cwd);
+  const rel = relative(base, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(
+      `[envlock] Invalid env file path: "${envFile}" resolves outside the project directory.`
+    );
+  }
+}
+
+// src/cli/resolve-config.ts
+import { existsSync } from "fs";
+import { resolve as resolve2 } from "path";
+import { pathToFileURL } from "url";
+var CONFIG_CANDIDATES = [
+  "envlock.config.js",
+  "envlock.config.mjs"
+];
+async function resolveConfig(cwd) {
+  for (const candidate of CONFIG_CANDIDATES) {
+    const fullPath = resolve2(cwd, candidate);
+    if (!existsSync(fullPath)) continue;
+    try {
+      const mod = await import(pathToFileURL(fullPath).href);
+      const config = mod.default ?? mod;
+      if (config && typeof config === "object") {
+        return config;
+      }
+    } catch (err) {
+      console.warn(
+        `[envlock] Failed to load ${candidate}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  return null;
+}
+
+// src/cli/index.ts
+var ARGUMENT_FLAGS = {
+  staging: "--staging",
+  production: "--production"
+};
+var DEFAULT_ENV_FILES = {
+  development: ".env.development",
+  staging: ".env.staging",
+  production: ".env.production"
+};
+function splitCommand(cmd) {
+  const parts = [];
+  const re = /[^\s"']+|"([^"]*)"|'([^']*)'/g;
+  let match;
+  while ((match = re.exec(cmd)) !== null) {
+    parts.push(match[1] ?? match[2] ?? match[0]);
+  }
+  return parts;
+}
+async function run(argv, cwd = process.cwd()) {
+  const environment = argv.includes(ARGUMENT_FLAGS.production) ? ENVIRONMENTS.production : argv.includes(ARGUMENT_FLAGS.staging) ? ENVIRONMENTS.staging : ENVIRONMENTS.development;
+  const passthrough = argv.filter(
+    (f) => f !== ARGUMENT_FLAGS.staging && f !== ARGUMENT_FLAGS.production
+  );
+  const config = await resolveConfig(cwd);
+  const firstArg = passthrough[0];
+  let command;
+  let args;
+  if (firstArg === void 0) {
+    const available = config?.commands ? Object.keys(config.commands).join(", ") : "none";
+    throw new Error(`[envlock] No command specified. Available commands: ${available}`);
+  }
+  if (firstArg === "run") {
+    if (config?.commands?.["run"]) {
+      console.warn(
+        '[envlock] Warning: "run" is a reserved subcommand. The config command named "run" is ignored.\nRename it in envlock.config.js to use it as a named command.'
+      );
+    }
+    const runArgs = passthrough.slice(1);
+    if (runArgs.length === 0) {
+      throw new Error(
+        "[envlock] Usage: envlock run <command> [args...]\nExample: envlock run node server.js --port 4000"
+      );
+    }
+    command = runArgs[0];
+    args = runArgs.slice(1);
+  } else if (config?.commands && firstArg in config.commands) {
+    const cmdString = config.commands[firstArg];
+    if (!cmdString || cmdString.trim() === "") {
+      throw new Error(`[envlock] Command "${firstArg}" is empty in envlock.config.js.`);
+    }
+    const parts = splitCommand(cmdString);
+    command = parts[0];
+    args = parts.slice(1);
+  } else if (config?.commands && Object.keys(config.commands).length > 0 && passthrough.length === 1) {
+    throw new Error(
+      `[envlock] Unknown command "${firstArg}". Available: ${Object.keys(config.commands).join(", ")}`
+    );
+  } else {
+    command = firstArg;
+    args = passthrough.slice(1);
+  }
+  const onePasswordEnvId = process.env["ENVLOCK_OP_ENV_ID"] ?? config?.onePasswordEnvId;
+  if (!onePasswordEnvId) {
+    throw new Error(
+      "[envlock] No onePasswordEnvId found. Set it in envlock.config.js or via ENVLOCK_OP_ENV_ID env var."
+    );
+  }
+  validateOnePasswordEnvId(onePasswordEnvId);
+  const envFile = config?.envFiles?.[environment] ?? DEFAULT_ENV_FILES[environment];
+  validateEnvFilePath(envFile, cwd);
+  runWithSecrets({ envFile, environment, onePasswordEnvId, command, args });
+}
+if (import.meta.url === pathToFileURL2(process.argv[1] ?? "").href) {
+  run(process.argv.slice(2)).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}
+export {
+  run
+};

package/dist/index.d.ts

@@ -8,6 +8,15 @@ interface EnvlockOptions {
     onePasswordEnvId: string;
     envFiles?: Partial<Record<Environment, string>>;
 }
+interface EnvlockConfig {
+    /**
+     * Your 1Password Environment ID.
+     * Can alternatively be set via the ENVLOCK_OP_ENV_ID environment variable.
+     */
+    onePasswordEnvId?: string;
+    envFiles?: Partial<Record<Environment, string>>;
+    commands?: Record<string, string>;
+}
 
 interface RunWithSecretsOptions {
     envFile: string;
@@ -24,4 +33,4 @@ declare function checkBinary(name: string, installHint: string): void;
 declare function validateOnePasswordEnvId(id: string): void;
 declare function validateEnvFilePath(envFile: string, cwd: string): void;
 
-export { ENVIRONMENTS, type Environment, type EnvlockOptions, type RunWithSecretsOptions, checkBinary, hasBinary, runWithSecrets, validateEnvFilePath, validateOnePasswordEnvId };
+export { ENVIRONMENTS, type Environment, type EnvlockConfig, type EnvlockOptions, type RunWithSecretsOptions, checkBinary, hasBinary, runWithSecrets, validateEnvFilePath, validateOnePasswordEnvId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envlock-core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Core 1Password + dotenvx secret injection logic for envlock",
   "license": "MIT",
@@ -17,25 +17,26 @@
   "engines": {
     "node": ">=18"
   },
+  "bin": {
+    "envlock": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
-  "files": [
-    "dist"
-  ],
-  "devDependencies": {
-    "@types/node": "^20.14.10",
-    "tsup": "^8.0.0",
-    "typescript": "^5.8.2",
-    "vitest": "^3.0.0"
-  },
+  "files": ["dist"],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.0"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Benjamin Davies
-
-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.