yamlock 0.2.8 → 0.3.0

package/README.md

@@ -60,6 +60,9 @@ yamlock algorithms
 
 # Generate a random key for YAMLOCK_KEY
 yamlock keygen --length 64 --format base64
+
+# Preview changes without touching files
+yamlock encrypt config.yml -o config.enc.yml -p db.password -k "my-secret-key" -d
 ```
 
 The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writes the file back in the same format.
@@ -67,6 +70,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.
@@ -116,11 +120,36 @@ const restored = processConfig(processed, {
   key: KEY,
   algorithm: { algorithm: 'aes-192-cbc', ivLength: 24 }
 });
+
+// Control what happens when encountering non-string values and customize path IDs
+const mixedConfig = { db: { password: 'secret', retries: 3 } };
+const lockedMixed = processConfig(mixedConfig, {
+  mode: 'encrypt',
+  key: KEY,
+  nonStringPolicy: 'stringify', // stringifies numbers/objects before encrypting
+  pathSerializer: (segments) => segments.join('/') // custom path naming (db/password instead of dot notation)
+});
+
+// Example of a path serializer that includes array indexes explicitly
+const lockedUsers = processConfig(
+  { users: [{ tokens: ['abc'] }] },
+  {
+    mode: 'encrypt',
+    key: KEY,
+    pathSerializer: (segments) =>
+      segments
+        .map((segment, index) =>
+          typeof segment === 'number' ? `[${segment}]` : index === 0 ? segment : `/${segment}`
+        )
+        .join('')
+  }
+);
 ```
 
 ## Advanced usage
 
 - **Selective encryption**: combine `--paths` on the CLI or `paths: []` in `processConfig` to encrypt only sensitive sections of a config file.
+- **Non-string handling**: use `nonStringPolicy: 'ignore' | 'stringify' | 'error'` to control how numbers/objects are treated, and `pathSerializer` to change how traversal paths are represented (e.g., `db/password` instead of dot notation).
 - **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.
 

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/dist/utils/config.js

@@ -15,6 +15,8 @@ const MODES = {
  * @param {string|Buffer} options.key
  * @param {string|object} [options.algorithm]
  * @param {object} [options.algorithmOptions]
+ * @param {"ignore"|"stringify"|"error"} [options.nonStringPolicy]
+ * @param {(segments: Array<string|number>) => string} [options.pathSerializer]
  * @param {string[]} [options.paths]
  * @param {Array<string|number>} [options.parentPath]
  * @returns {Object|Array}
@@ -37,11 +39,13 @@ export function processConfig(node, options) {
     ...options,
     mode,
     parentPath: options.parentPath ?? [],
-    normalizedPaths
+    normalizedPaths,
+    nonStringPolicy: options.nonStringPolicy ?? 'ignore',
+    pathSerializer: options.pathSerializer
   });
 }
 
-function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPath, normalizedPaths }) {
+function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPath, normalizedPaths, nonStringPolicy, pathSerializer }) {
   const isArrayNode = Array.isArray(node);
   const result = isArrayNode ? [] : {};
   const cryptoOptions = algorithmOptions ?? algorithm;
@@ -49,7 +53,9 @@ function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPa
   Object.entries(node).forEach(([rawKey, value]) => {
     const segment = isArrayNode ? Number(rawKey) : rawKey;
     const targetKey = isArrayNode ? segment : rawKey;
-    const currentPath = buildPath(parentPath, segment);
+    const currentPath = pathSerializer
+      ? pathSerializer([...parentPath, segment])
+      : buildPath(parentPath, segment);
 
     if (value !== null && typeof value === 'object') {
       result[targetKey] = traverseConfig(value, {
@@ -58,14 +64,22 @@ function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPa
         algorithm: cryptoOptions,
         algorithmOptions: cryptoOptions,
         parentPath: [...parentPath, segment],
-        normalizedPaths
+        normalizedPaths,
+        nonStringPolicy,
+        pathSerializer
       });
       return;
     }
 
     if (typeof value !== 'string') {
-      result[targetKey] = value;
-      return;
+      if (nonStringPolicy === 'stringify') {
+        value = JSON.stringify(value);
+      } else if (nonStringPolicy === 'error') {
+        throw new Error(`Non-string value encountered at ${currentPath}`);
+      } else {
+        result[targetKey] = value;
+        return;
+      }
     }
 
     const shouldProcess = !normalizedPaths || normalizedPaths.has(currentPath);

package/package.json

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