envlock-core 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,13 @@
 
 Framework-agnostic 1Password + dotenvx secret injection logic.
 
-> Most users should install [`envlock`](https://www.npmjs.com/package/envlock) instead. This package is for integrating envlock with frameworks other than Next.js.
+> 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
 
@@ -10,33 +16,64 @@ Framework-agnostic 1Password + dotenvx secret injection logic.
 pnpm add envlock-core
 ```
 
-## API
-
-### `runWithSecrets(options)`
+## Usage
 
-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.
+### `envlock.config.js`
 
-```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 |
-|--------|------|-------------|
-| `envFile` | `string` | Path to the encrypted dotenvx env file |
-| `environment` | `string` | Environment name (`development`, `staging`, `production`) |
-| `onePasswordEnvId` | `string` | Your 1Password Environment ID |
-| `command` | `string` | The command to run |
-| `args` | `string[]` | Arguments to pass to the command |
+| Option             | Type          | Description                                               |
+| ------------------ | ------------- | --------------------------------------------------------- |
+| `envFile`          | `string`      | Path to the encrypted dotenvx env file                    |
+| `environment`      | `Environment` | Environment name (`development`, `staging`, `production`) |
+| `onePasswordEnvId` | `string`      | Your 1Password Environment ID                             |
+| `command`          | `string`      | The command to run                                        |
+| `args`             | `string[]`    | Arguments to pass to the command                          |
 
 ### `validateOnePasswordEnvId(id)`
 
@@ -57,20 +94,28 @@ Calls `process.exit(1)` with a helpful message if `name` is not in `PATH`.
 ## Types
 
 ```ts
-type Environment = 'development' | 'staging' | 'production';
+const ENVIRONMENTS = {
+  development: 'development',
+  staging: 'staging',
+  production: 'production',
+} as const;
+
+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?: {
-    development?: string;
-    staging?: string;
-    production?: string;
-  };
+  envFiles?: Partial<Record<Environment, string>>;
 }
 
 interface RunWithSecretsOptions {
   envFile: string;
-  environment: string;
+  environment: Environment;
   onePasswordEnvId: string;
   command: string;
   args: string[];

package/dist/cli/index.js

@@ -0,0 +1,195 @@
+#!/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 (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

@@ -1,6 +1,26 @@
+declare const ENVIRONMENTS: {
+    readonly development: "development";
+    readonly staging: "staging";
+    readonly production: "production";
+};
+type Environment = keyof typeof ENVIRONMENTS;
+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;
-    environment: string;
+    environment: Environment;
     onePasswordEnvId: string;
     command: string;
     args: string[];
@@ -13,14 +33,4 @@ declare function checkBinary(name: string, installHint: string): void;
 declare function validateOnePasswordEnvId(id: string): void;
 declare function validateEnvFilePath(envFile: string, cwd: string): void;
 
-type Environment = "development" | "staging" | "production";
-interface EnvlockOptions {
-    onePasswordEnvId: string;
-    envFiles?: {
-        development?: string;
-        staging?: string;
-        production?: string;
-    };
-}
-
-export { 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/dist/index.js

@@ -85,7 +85,15 @@ function validateEnvFilePath(envFile, cwd) {
     );
   }
 }
+
+// src/types.ts
+var ENVIRONMENTS = {
+  development: "development",
+  staging: "staging",
+  production: "production"
+};
 export {
+  ENVIRONMENTS,
   checkBinary,
   hasBinary,
   runWithSecrets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envlock-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Core 1Password + dotenvx secret injection logic for envlock",
   "license": "MIT",
@@ -17,6 +17,9 @@
   "engines": {
     "node": ">=18"
   },
+  "bin": {
+    "envlock": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",