sops-env 0.0.0-stage → 1.0.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# sops-env
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Print the `env` section of a [SOPS](https://github.com/getsops/sops)-encrypted file as `KEY=VALUE` lines.
+
+## Requirements
+
+- Node.js 22 or later, or Bun
+- [`sops`](https://github.com/getsops/sops) in `PATH`, with access to the decryption key
+
+## Usage
+
+Keep the environment variables under the `env` key of a SOPS file; other keys are ignored.
+Name the variables with ASCII letters, digits, and `_`, and do not start a name with a digit.
+An encrypted file `environment.sops.yaml` looks like this:
+
+```yaml
+env:
+  NODE_ENV: ENC[AES256_GCM,data:66pExK+Z2weH0g==,iv:…,tag:…,type:str]
+  PORT: ENC[AES256_GCM,data:8hoeUQ==,iv:…,tag:…,type:int]
+  SECRET_KEY: ENC[AES256_GCM,data:4+CiTc2C,iv:…,tag:…,type:str]
+sops:
+  # Encrypted data keys and metadata
+```
+
+Print the decrypted variables as lines of an environment file:
+
+```sh
+npx sops-env environment.sops.yaml
+```
+
+```sh
+NODE_ENV=production
+PORT=3000
+SECRET_KEY=s3cr3t
+```
+
+Values are printed as is, without quoting or escaping, so the command fails when a value spans several lines.
+
+### Set variables in Dokku
+
+Pass `--base64` to print every value base64-encoded, as `dokku config:set --encoded` expects; multi-line values are allowed:
+
+```sh
+ssh dokku@example.com config:set --encoded my-app $(npx sops-env --base64 environment.sops.yaml)
+```
+
+The unquoted substitution splits the output into one argument per variable.
+A failed command inside it does not stop the script, so in a script assign the output to a variable first and stop on failure, instead of running `config:set` without variables:
+
+```sh
+config=$(npx sops-env --base64 environment.sops.yaml) || exit
+ssh dokku@example.com config:set --encoded my-app $config
+```
+
+### Values
+
+- Strings, numbers, and booleans are printed as text, such as `PORT=3000` and `DEBUG=true`.
+- Quote a value to keep its exact text: sops rewrites unquoted numbers and dates, such as `1.50` to `1.5`, `0x10` to `16`, and `2024-01-01` to `2024-01-01T00:00:00Z`.
+- `null`, lists, and maps are rejected: quote a value, such as `EMPTY: ''`, to print it as text.

package/dist/cli.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
+import { constants } from "node:os";
+// src/error.ts
+/** Error that the CLI reports to the user as a message without a stack trace. */
+var SopsEnvError = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1) {
+		super(message);
+		this.exitCode = exitCode;
+		this.name = "SopsEnvError";
+	}
+};
+// src/env.ts
+/**
+* Formats the `env` section of a decrypted document as `KEY=VALUE` lines.
+*
+* Names are written as is and must be shell identifiers, so that no name makes a line ambiguous.
+* Without `base64`, values are written as is, without quoting, so multi-line values are rejected.
+*/
+function formatEnv(document, { base64 = false } = {}) {
+	const env = isRecord(document) ? document.env : void 0;
+	if (!isRecord(env)) throw new SopsEnvError("The env section is missing or is not a mapping. Put the variables under the env key of a YAML or JSON file; dotenv files are not supported.");
+	const invalidNames = Object.keys(env).filter((key) => !isValidName(key));
+	if (invalidNames.length) throw new SopsEnvError(`Unsupported variable names: ${invalidNames.map(quoteName).join(", ")}. A name must consist of ASCII letters, digits, and _, and must not start with a digit.`);
+	const entries = Object.entries(env).map(([key, value]) => [key, toEnvValue(key, value)]);
+	if (!base64) {
+		const multiline = entries.filter(([, value]) => value.includes("\n")).map(([key]) => key);
+		if (multiline.length) throw new SopsEnvError(`Multi-line values are not supported: ${multiline.join(", ")}`);
+	}
+	return entries.map(([key, value]) => `${key}=${base64 ? Buffer.from(value).toString("base64") : value}`).join("\n");
+}
+/**
+* Checks that a variable name is a shell identifier: ASCII letters, digits, and `_`, not starting with a digit.
+*
+* Shells and Dokku accept only such names, and they cannot make a `KEY=VALUE` line ambiguous,
+* unlike names with `=`, line breaks, whitespace, or a leading `#`.
+*/
+function isValidName(name) {
+	return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
+/**
+* Quotes a variable name for an error message.
+*
+* Escapes non-space whitespace, control characters, and format characters left literal by `JSON.stringify`,
+* as `\uXXXX` per UTF-16 code unit, so that a character beyond U+FFFF becomes a surrogate pair.
+*/
+function quoteName(name) {
+	return JSON.stringify(name).replace(/[^\S ]|[\p{Cc}\p{Cf}]/gu, (char) => char.split("").map((unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`).join(""));
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Converts a scalar value to its string form; rejects null and collections. */
+function toEnvValue(key, value) {
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+	throw new SopsEnvError(`Unsupported value of ${key}: expected a string, number, or boolean.`);
+}
+// src/sops.ts
+/**
+* Decrypts a SOPS file with the `sops` CLI and returns the parsed document.
+*
+* Numbers are returned as their JSON source text, so that integers beyond the double precision keep every digit.
+* Throws a `SopsEnvError` with the exit code that a shell would report for sops:
+* its own exit code, 128 plus the signal number when a signal kills it, or 127 when it is missing.
+* Only a missing sops gets a message; stderr of sops is inherited.
+*/
+function decryptFile(path) {
+	const result = spawnSync("sops", [
+		"decrypt",
+		"--output-type",
+		"json",
+		path
+	], {
+		encoding: "utf8",
+		maxBuffer: Number.POSITIVE_INFINITY,
+		stdio: [
+			"ignore",
+			"pipe",
+			"inherit"
+		]
+	});
+	if (result.error) {
+		if (result.error.code === "ENOENT") throw new SopsEnvError("sops is not installed or not in PATH.", 127);
+		throw result.error;
+	}
+	if (result.signal) throw new SopsEnvError("", 128 + constants.signals[result.signal]);
+	if (result.status !== 0) throw new SopsEnvError("", result.status ?? 1);
+	return parseJson(result.stdout);
+}
+/** Parses JSON, returning numbers as their source text. */
+function parseJson(text) {
+	return JSON.parse(text, (_key, value, context) => typeof value === "number" && context?.source !== void 0 ? context.source : value);
+}
+// src/cli.ts
+const usage = "Usage: sops-env [--base64] <environment.sops.yaml>";
+const help = `${usage}
+
+Print the env section of a SOPS-encrypted file as KEY=VALUE lines.
+Multi-line values are rejected.
+
+Options:
+  --base64    Encode values in base64; allows multi-line values
+  -h, --help  Show this help
+`;
+const options = {
+	base64: { type: "boolean" },
+	help: {
+		type: "boolean",
+		short: "h"
+	}
+};
+function main(args) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args,
+			allowPositionals: true,
+			options
+		});
+	} catch (error) {
+		throw new SopsEnvError(`${error.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? `Unknown option '${findUnknownOption(args)}'.` : error.message}\n${usage}`);
+	}
+	const { values, positionals } = parsed;
+	if (values.help) {
+		process.stdout.write(help);
+		return;
+	}
+	if (positionals.length !== 1) throw new SopsEnvError(usage);
+	const output = formatEnv(decryptFile(positionals[0]), { base64: values.base64 });
+	if (output) process.stdout.write(`${output}\n`);
+}
+/** Returns the first option in `args` that the CLI does not define, as the user wrote it. */
+function findUnknownOption(args) {
+	const { tokens } = parseArgs({
+		args,
+		allowPositionals: true,
+		options,
+		strict: false,
+		tokens: true
+	});
+	for (const token of tokens) if (token.kind === "option" && !Object.hasOwn(options, token.name)) return token.rawName;
+}
+try {
+	main(process.argv.slice(2));
+} catch (error) {
+	if (!(error instanceof SopsEnvError)) throw error;
+	if (error.message) process.stderr.write(`${error.message}\n`);
+	process.exitCode = error.exitCode;
+}
+export {};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "sops-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Print the env section of a SOPS-encrypted file as KEY=VALUE lines, optionally with base64-encoded values.",
+  "keywords": [
+    "cli",
+    "dokku",
+    "dotenv",
+    "env",
+    "secrets",
+    "sops"
+  ],
+  "homepage": "https://github.com/IlyaSemenov/sops-env#readme",
+  "bugs": "https://github.com/IlyaSemenov/sops-env/issues",
+  "license": "MIT",
+  "author": "Ilya Semenov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IlyaSemenov/sops-env.git"
+  },
+  "bin": {
+    "sops-env": "./dist/cli.mjs"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint --fix && oxfmt",
+    "lint:check": "oxlint && oxfmt --check",
+    "prepare": "lefthook install",
+    "prepublishOnly": "bun run build",
+    "release": "changesets-local",
+    "release:check": "bun run build && bun run types && bun run test",
+    "test": "bun test",
+    "types": "bun check && bun check -p tests"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@ilyasemenov/oxc-config": "^0.1.3",
+    "@tsconfig/bun": "^1.0.12",
+    "@types/bun": "^1.4.4",
+    "changesets-local": "^1.6.0",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.7",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "bun@1.4.4"
+}