yamlock 0.2.5 → 0.2.9

package/README.md

@@ -4,6 +4,9 @@
 ░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░
 ```
 
+[![npm version](https://img.shields.io/npm/v/yamlock)](https://www.npmjs.com/package/yamlock)
+[![Tests](https://img.shields.io/badge/tests-node--test-green)](https://github.com/phoenixweiss/yamlock/actions)
+
 # yamlock
 
 Value-level encryption for YAML and JSON configuration files. The name **yamlock** combines "YAML" and "lock" while also sounding like "warlock", hinting at a little configuration magic.
@@ -64,6 +67,7 @@ The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writ
 Options of note:
 - `--output <file>` writes the result to a separate file instead of overwriting the input.
 - `--paths <path1,path2>` targets only the specified fields (dot/bracket notation like `db.password` or `users[0].token`).
+- `--dry-run` shows the would-be changes without modifying files (prints original vs new content).
 - Command `keygen` produces a random key and shows how to store it (shell export or `.env`).
 - Command `algorithms` prints two lists: tested presets (covered by yamlock) and additional ciphers available from the runtime.
 - Command `version` prints the installed CLI version.
@@ -115,6 +119,12 @@ const restored = processConfig(processed, {
 });
 ```
 
+## Advanced usage
+
+- **Selective encryption**: combine `--paths` on the CLI or `paths: []` in `processConfig` to encrypt only sensitive sections of a config file.
+- **CI/CD flows**: see [examples/docs/ci-cd.md](examples/docs/ci-cd.md) for a GitHub Actions job that decrypts configs for builds and re-encrypts them before publishing artifacts.
+- **Key rotation**: follow [examples/docs/key-rotation.md](examples/docs/key-rotation.md) for a step-by-step process, including scripting tips for large repos.
+
 ### Supported algorithms
 
 | Algorithm | Type | Notes |
@@ -126,6 +136,11 @@ const restored = processConfig(processed, {
 
 You can also pass any algorithm supported by the current Node.js runtime (`crypto.getCiphers()`), along with custom `keyLength`, `ivLength`, or `authTagLength` overrides. Only the algorithms above are actively tested; additional presets may be added or revised in future releases.
 
+## Release information
+
+- The badges at the top show the latest npm version and the status of the Node test suite.
+- See [CHANGELOG.md](CHANGELOG.md) for detailed release notes; install a specific tag via `npm install yamlock@<version>`.
+
 ### Encrypted value format
 
 Every locked string follows the format:

package/dist/cli/cli.js

@@ -37,6 +37,7 @@ Options:
   -a, --algorithm <value>  Cipher algorithm (default: aes-256-cbc).
   -o, --output <file>      Write the result to a different file (otherwise overwrites the input file).
   -p, --paths <p1,p2>      Comma-separated list of field paths to process (dot/bracket notation).
+  -d, --dry-run             Show the diff without modifying files.
   --length <bytes>         (keygen) Number of random bytes to generate (default: 32).
   --format <hex|base64>    (keygen) Output format (default: base64).
 `;
@@ -64,21 +65,22 @@ function readConfigFile(filePath) {
   const format = detectFormat(filePath);
 
   if (format === 'yaml') {
-    return { format, data: yaml.load(content) ?? {} };
+    return { format, data: yaml.load(content) ?? {}, raw: content };
   }
 
-  return { format, data: JSON.parse(content) };
+  return { format, data: JSON.parse(content), raw: content };
 }
 
-function writeConfigFile(filePath, format, data) {
+function serializeConfig(format, data) {
   if (format === 'yaml') {
-    const serialized = yaml.dump(data, { lineWidth: 120 });
-    writeFileSync(filePath, serialized, 'utf8');
-    return;
+    return yaml.dump(data, { lineWidth: 120 });
   }
 
-  const serialized = JSON.stringify(data, null, 2);
-  writeFileSync(filePath, `${serialized}\n`, 'utf8');
+  return `${JSON.stringify(data, null, 2)}\n`;
+}
+
+function writeConfigFile(filePath, serialized) {
+  writeFileSync(filePath, serialized, 'utf8');
 }
 
 function parsePaths(value) {
@@ -97,7 +99,7 @@ function parseArgs(argv) {
   const result = {
     command: args[0],
     file: undefined,
-    options: {}
+    options: { dryRun: false }
   };
 
   let index = 1;
@@ -131,9 +133,15 @@ function parseArgs(argv) {
     } else if (arg === '--format') {
       result.options.format = next;
       i += 1;
+    } else if (arg === '-d' || arg === '--dry-run') {
+      result.options.dryRun = true;
     }
   }
 
+  if (result.options.dryRun && result.command && !result.file && !['version', 'algorithms', 'keygen'].includes(result.command)) {
+    // dry-run without file is invalid, but we'll let later validation handle file requirement
+  }
+
   return result;
 }
 
@@ -146,6 +154,30 @@ function generateRandomKey(length, format) {
   return buffer.toString('base64');
 }
 
+function fail(code, message) {
+  printError(`[yamlock:${code}] ${message}`);
+  return exit(1);
+}
+
+function handleWrite({ dryRun, file, outputPath, format, originalRaw, data, operation }) {
+  const serialized = serializeConfig(format, data);
+  if (dryRun) {
+    print(`DRY-RUN (${operation}) ${file}`);
+    print('--- original');
+    print((originalRaw ?? '').trimEnd());
+    print('+++ result');
+    print(serialized.trimEnd());
+    if (outputPath !== file) {
+      print(`(would write to ${outputPath})`);
+    }
+    print('No files were modified.');
+    return;
+  }
+
+  writeConfigFile(outputPath, serialized);
+  print(`${operation === 'encrypt' ? 'Encrypted' : 'Decrypted'} values in ${outputPath}`);
+}
+
 export async function runCli(argv = process.argv) {
   const { command, file, options } = parseArgs(argv);
 
@@ -181,13 +213,11 @@ export async function runCli(argv = process.argv) {
     const normalizedFormat = (options.format ?? 'base64').toLowerCase();
 
     if (!Number.isFinite(desiredLength) || desiredLength <= 0) {
-      printError('Key length must be a positive number.');
-      return exit(1);
+      return fail('ERR_INVALID_LENGTH', 'Key length must be a positive number.');
     }
 
     if (!['base64', 'hex'].includes(normalizedFormat)) {
-      printError('Key format must be either "base64" or "hex".');
-      return exit(1);
+      return fail('ERR_INVALID_FORMAT', 'Key format must be either "base64" or "hex".');
     }
 
     const keyValue = generateRandomKey(desiredLength, normalizedFormat);
@@ -200,15 +230,13 @@ export async function runCli(argv = process.argv) {
   }
 
   if (!file) {
-    printError('A file path is required for this command.');
     print(getHelpText().trim());
-    return exit(1);
+    return fail('ERR_FILE_REQUIRED', 'A file path is required for this command.');
   }
 
   const key = options.key ?? process.env.YAMLOCK_KEY;
   if (!key) {
-    printError('Encryption key is required via --key or YAMLOCK_KEY.');
-    return exit(1);
+    return fail('ERR_MISSING_KEY', 'Encryption key is required via --key or YAMLOCK_KEY.');
   }
 
   const absolutePath = resolve(process.cwd(), file);
@@ -216,8 +244,7 @@ export async function runCli(argv = process.argv) {
   try {
     config = readConfigFile(absolutePath);
   } catch (error) {
-    printError(`Failed to read config file: ${error.message}`);
-    return exit(1);
+    return fail('ERR_READ_FAILED', `Failed to read config file: ${error.message}`);
   }
 
   const outputPath = options.output
@@ -232,8 +259,15 @@ export async function runCli(argv = process.argv) {
         algorithm: options.algorithm,
         paths: options.paths
       });
-      writeConfigFile(outputPath, config.format, result);
-      print(`Encrypted values in ${outputPath === absolutePath ? file : options.output}`);
+      handleWrite({
+        dryRun: options.dryRun,
+        file,
+        outputPath,
+        format: config.format,
+        originalRaw: config.raw,
+        data: result,
+        operation: 'encrypt'
+      });
       return exit(0);
     }
 
@@ -244,17 +278,22 @@ export async function runCli(argv = process.argv) {
         algorithm: options.algorithm,
         paths: options.paths
       });
-      writeConfigFile(outputPath, config.format, result);
-      print(`Decrypted values in ${outputPath === absolutePath ? file : options.output}`);
+      handleWrite({
+        dryRun: options.dryRun,
+        file,
+        outputPath,
+        format: config.format,
+        originalRaw: config.raw,
+        data: result,
+        operation: 'decrypt'
+      });
       return exit(0);
     }
 
-    printError(`Unknown command: ${command}`);
     print(getHelpText().trim());
-    return exit(1);
+    return fail('ERR_UNKNOWN_COMMAND', `Unknown command: ${command}`);
   } catch (error) {
-    printError(`Operation failed: ${error.message}`);
-    return exit(1);
+    return fail('ERR_PROCESS_FAILED', `Operation failed: ${error.message}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlock",
-  "version": "0.2.5",
+  "version": "0.2.9",
   "author": "PAVEL TKACHEV (phoenixweiss) <mail@phoenixweiss.me>",
   "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
   "license": "MIT",