sops-env 1.0.0 → 1.0.1

package/README.md

@@ -10,6 +10,7 @@ Print the `env` section of a [SOPS](https://github.com/getsops/sops)-encrypted f
 ## 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
@@ -54,5 +55,5 @@ 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`.
-- sops normalizes numbers, such as `1.50` to `1.5`; quote a value to keep its exact text.
+- 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

@@ -16,11 +16,14 @@ var SopsEnvError = class extends Error {
 /**
 * 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.");
+	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);
@@ -28,6 +31,24 @@ function formatEnv(document, { base64 = false } = {}) {
 	}
 	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);
 }
@@ -83,22 +104,23 @@ 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: {
-				base64: { type: "boolean" },
-				help: {
-					type: "boolean",
-					short: "h"
-				}
-			}
+			options
 		});
 	} catch (error) {
-		throw new SopsEnvError(`${error.message}\n${usage}`);
+		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) {
@@ -109,6 +131,17 @@ function main(args) {
 	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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sops-env",
-  "version": "1.0.0",
+  "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",