envilder 0.2.3 → 0.3.1

package/.github/workflows/unit-tests.yml

@@ -1,48 +1,51 @@
-name: 🌱 unit-tests
-
-on:
-  workflow_dispatch: {}
-
-  pull_request:
-    branches:
-      - "*"
-    types:
-      - opened
-      - reopened
-      - synchronize
-      - ready_for_review
-    paths:
-      - ".github/workflows/unit-tests.yml"
-      - "src/**"
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
-  cancel-in-progress: true
-
-jobs:
-  envilder-test:
-    runs-on: ubuntu-24.04
-    if: ${{ !github.event.pull_request.draft }}
-    timeout-minutes: 30
-
-    steps:
-      - name: 🚀 ♂️ Checkout
-        uses: actions/checkout@v4
-
-      - name: 🛠️ Setup Node.js with Cache
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          cache: 'yarn'
-
-      - name: 📦 Install packages
-        run: yarn install
-
-      - name: 🔍 Run code quality checker
-        run: yarn lint
-
-      - name: 🚧 Build
-        run: yarn build
-
-      - name: 🚴‍♀️ Run unit tests
-        run: yarn test
+name: 🌱 unit-tests
+
+on:
+  workflow_dispatch: {}
+
+  pull_request:
+    branches:
+      - "*"
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+    paths:
+      - ".github/workflows/unit-tests.yml"
+      - "src/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  envilder-test:
+    runs-on: ubuntu-24.04
+    if: ${{ !github.event.pull_request.draft }}
+    timeout-minutes: 30
+
+    steps:
+      - name: 🚀 ♂️ Checkout
+        uses: actions/checkout@v4
+
+      - name: 🛠️ Setup Node.js with Cache
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'yarn'
+
+      - name: 📦 Install packages
+        run: yarn install --frozen-lockfile
+
+      - name: 🔍 Run formatting checker
+        run: yarn format
+
+      - name: 🔍 Run code quality checker
+        run: yarn lint
+
+      - name: 🚧 Build
+        run: yarn build
+
+      - name: 🚴‍♀️ Run unit tests
+        run: yarn test

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Marçal Albert
-
-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.
+MIT License
+
+Copyright (c) 2024 Marçal Albert
+
+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,95 +1,144 @@
-![Envilder](https://github.com/user-attachments/assets/f646a3e7-6ae2-4f3b-8f51-3807067fc99c)
-
-Envilder is a CLI tool for managing AWS SSM Parameter Store parameters and automatically generating the required `.env` file. This tool simplifies project environment variable management, avoiding manual updates and ensuring consistency across environments.
-
-# ✨ Features
-
-- 🔒 Fetch parameters securely from AWS SSM Parameter Store.
-- ⚡ Automatically generates a `.env` file with specified parameters.
-- 🛡️ Handles encrypted (currently only supported) SSM parameters.
-- 🪶 Lightweight and simple to use.
-
-# Prerequisites
-Before using `Envilder`, ensure that you have the AWS CLI installed and properly configured on your local machine. This configuration is required for `Envilder` to access and manage parameters in AWS SSM.
-
-## AWS CLI Installation & Configuration
-1. Install the AWS CLI by following the instructions [here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
-2. After installation, configure the AWS CLI using the following command:
-
-    ```bash
-    aws configure
-    ```
-
-    You'll be prompted to provide:
-    - AWS Access Key ID
-    - AWS Secret Access Key
-    - Default region name (e.g., `us-east-1`)
-    - Default output format (e.g., `json`)
-
-   Make sure that the AWS credentials you're using have the appropriate permissions to access the SSM Parameter Store in your AWS account.
-
-# Installation
-You can install `Envilder` globally using yarn. This will allow you to use the `envilder` command from any directory on your system.
-
-```bash
-yarn global add envilder
-```
-
-# 📦 Installation
-
-You can install **envilder** globally or locally using npm:
-
-```bash
-npm install -g envilder
-```
-
-# 🚀 Usage
-
-Envilder requires two arguments:
-
-- `--map <path>`: Path to a JSON file mapping environment variable names to SSM parameters.
-- `--envfile <path>`: Path where the generated .env file will be saved.
-
-# 🔧 Example
-
-1. Create a mapping file `param_map.json`:
-
-    ```json
-    {
-      "SECRET_TOKEN": "/path/to/ssm/token",
-      "SECRET_KEY": "/path/to/ssm/password"
-    }
-    ```
-
-2. Run envilder to generate your `.env` file:
-
-    ```bash
-    envilder --map=param_map.json --envfile=.env
-    ```
-
-3. The `.env` file will be generated in the specified location.
-
-# 📂 Sample `.env` Output
-
-```makefile
-SECRET_TOKEN=mockedEmail@example.com
-SECRET_KEY=mockedPassword
-```
-
-# 🧪 Running Tests
-
-To run the tests with coverage: 
-
-```bash
-yarn test
-```
-
-Here you can see the current coverage report: https://macalbert.github.io/envilder/
-
-# 📝 License
-
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
-
-# 🙌 Contributing
-
-Contributions are welcome! Feel free to submit issues and pull requests.
+![Envilder](https://github.com/user-attachments/assets/f646a3e7-6ae2-4f3b-8f51-3807067fc99c)
+
+Envilder is a CLI tool for managing AWS SSM Parameter Store parameters and automatically generating the required
+`.env` file. This tool simplifies project environment variable management, avoiding manual updates and ensuring
+consistency across environments.
+
+# ✨ Features
+
+- 🔒 Fetch parameters securely from AWS SSM Parameter Store.
+- ⚡ Automatically generates a `.env` file with specified parameters.
+- 🛡️ Handles encrypted SSM parameters.
+- 🪶 Lightweight and simple to use.
+- 🔄 Support for multiple AWS profiles.
+
+# Prerequisites
+
+Before using `Envilder`, ensure that you have the AWS CLI installed and properly configured on your local
+machine. This configuration is required for `Envilder` to access and manage parameters in AWS SSM.
+
+## AWS CLI Installation & Configuration
+
+1. Install the AWS CLI by following the instructions [here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+2. After installation, configure the AWS CLI using the following command:
+
+    ```bash
+    aws configure
+    ```
+
+    You'll be prompted to provide:
+    - AWS Access Key ID
+    - AWS Secret Access Key
+    - Default region name (e.g., `us-east-1`)
+    - Default output format (e.g., `json`)
+
+   Make sure that the AWS credentials you're using have the appropriate permissions to access the SSM Parameter
+   Store in your AWS account.
+
+# Installation
+
+You can install `Envilder` globally using yarn. This will allow you to use the `envilder` command from any
+directory on your system.
+
+```bash
+yarn global add envilder
+```
+
+# 📦 Installation
+
+You can install **envilder** globally or locally using npm:
+
+```bash
+npm install -g envilder
+```
+
+# 🚀 Usage
+
+Envilder requires two arguments:
+
+- `--map <path>`: Path to a JSON file mapping environment variable names to SSM parameters.
+- `--envfile <path>`: Path where the generated .env file will be saved.
+
+Optional arguments:
+
+- `--profile <name>`: AWS CLI profile to use for credentials (if not using the default profile).
+
+# 🔧 Example
+
+1. Create a mapping file `param-map.json`:
+
+    ```json
+    {
+      "SECRET_TOKEN": "/path/to/ssm/token",
+      "SECRET_KEY": "/path/to/ssm/password"
+    }
+    ```
+
+2. Run envilder to generate your `.env` file:
+
+    ```bash
+    envilder --map=param-map.json --envfile=.env
+    ```
+
+3. To use a specific AWS profile:
+
+    ```bash
+    envilder --map=param-map.json --envfile=.env --profile=dev-account
+    ```
+
+4. The `.env` file will be generated in the specified location.
+
+## 🌐 Working with Multiple AWS Profiles
+
+If you work with multiple AWS accounts or environments, you can configure different profiles in your AWS credentials file:
+
+1. Edit your AWS credentials file (usually at `~/.aws/credentials` on Linux/Mac or `%USERPROFILE%\.aws\credentials` on Windows):
+
+    ```ini
+    [default]
+    aws_access_key_id=YOUR_DEFAULT_ACCESS_KEY
+    aws_secret_access_key=YOUR_DEFAULT_SECRET_KEY
+
+    [dev-account]
+    aws_access_key_id=YOUR_DEV_ACCESS_KEY
+    aws_secret_access_key=YOUR_DEV_SECRET_KEY
+
+    [prod-account]
+    aws_access_key_id=YOUR_PROD_ACCESS_KEY
+    aws_secret_access_key=YOUR_PROD_SECRET_KEY
+    ```
+
+2. When running Envilder, specify which profile to use with the `--profile` option:
+
+    ```bash
+    # For development environment
+    envilder --map=param-map.json --envfile=.env.development --profile=dev-account
+
+    # For production environment
+    envilder --map=param-map.json --envfile=.env.production --profile=prod-account
+    ```
+
+# 📂 Sample `.env` Output
+
+```makefile
+SECRET_TOKEN=mockedEmail@example.com
+SECRET_KEY=mockedPassword
+```
+
+# 🧪 Running Tests
+
+To run the tests with coverage:
+
+```bash
+yarn test
+```
+
+Here you can see the current coverage report: <https://macalbert.github.io/envilder/>
+
+# 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+# 🙌 Contributing
+
+Contributions are welcome! Feel free to submit issues and pull requests.

package/biome.json

@@ -1,17 +1,8 @@
 {
   "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
   "files": {
-    "include": [
-      "./src/**",
-      "./tests/**",
-      "package.json",
-      "biome.json",
-      ".secretlintrc.json",
-      "tsconfig.json",
-      "tsconfig.build.json",
-      "vite.config.ts",
-      "repopack.config.json"
-    ]
+    "include": ["./src/**", "./tests/**"],
+    "ignore": ["**/node_modules/**", "**/lib/**", "**/dist/**", "**/coverage/**", "**/.lock", "**/.md"]
   },
   "organizeImports": {
     "enabled": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envilder",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "A CLI tool to generate .env files from AWS SSM parameters",
   "exports": {
     ".": {
@@ -11,16 +11,19 @@
     "envilder": "lib/cli/cliRunner.js"
   },
   "scripts": {
-    "clean": "rimraf lib",
-    "test-run": "npm run build && node lib/cli/cliRunner.js --map=tests/sample/param_map.json --envfile=.env",
-    "build": "npm run clean && tsc -p tsconfig.build.json --sourceMap --declaration",
-    "lint": "biome lint --write && biome format --write && biome check --write && tsc --noEmit && secretlint **/*",
+    "clean": "npx jest --clearCache && yarn cache clean --force && npx rimraf lib && npx rimraf node_modules && npx rimraf coverage && npx rimraf yarn.lock",
+    "test-run": "yarn build && node lib/cli/cliRunner.js --map=tests/sample/param-map.json --envfile=tests/sample/autogenerated.env",
+    "build": "tsc -p tsconfig.build.json --sourceMap --declaration",
+    "format": "npx biome format",
+    "format:write": "npx biome format --write",
+    "lint": "npx secretlint \"**/*\" && biome lint --write && biome format --write && biome check --write && tsc --noEmit",
+    "lint:fix": "npx biome lint --fix",
     "test": "vitest run --reporter verbose --coverage",
-    "cli-run": "npm run build && node --trace-warnings lib",
-    "npm-publish": "npm run lint && npm run build && npm publish",
-    "npm-release-patch": "npm version patch && npm run npm-publish",
-    "npm-release-minor": "npm version minor && npm run npm-publish",
-    "npm-release-prerelease": "npm version prerelease && npm run npm-publish"
+    "cli-run": "yarn build && node --trace-warnings lib",
+    "npm-publish": "yarn lint && yarn build && yarn publish",
+    "npm-release-patch": "yarn version --new-version patch",
+    "npm-release-minor": "yarn version --new-version minor",
+    "npm-release-prerelease": "yarn version --new-version prerelease"
   },
   "keywords": [],
   "repository": {
@@ -37,29 +40,25 @@
   },
   "type": "module",
   "dependencies": {
-    "@aws-sdk/client-ssm": "^3.654.0",
-    "@secretlint/core": "^9.2.1",
-    "@secretlint/secretlint-rule-preset-recommend": "^9.0.0",
+    "@aws-sdk/client-ssm": "^3.806.0",
+    "@aws-sdk/credential-providers": "^3.806.0",
     "@types/node": "^22.5.5",
-    "commander": "^12.1.0",
+    "commander": "^13.1.0",
     "dotenv": "^16.4.5",
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.1",
+    "@secretlint/secretlint-rule-preset-recommend": "^9.3.2",
     "@vitest/coverage-v8": "^3.1.1",
     "rimraf": "^6.0.1",
-    "secretlint": "^9.0.0",
+    "secretlint": "^9.3.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.6.2",
     "vitest": "^3.1.1"
   },
-  "resolutions": {
-    "string-width": "4.2.3",
-    "strip-ansi": "6.0.1"
-  },
   "engines": {
     "node": ">=20.0.0",
     "yarn": ">=1.22"
   }
-}
+}

package/src/cli/cliRunner.ts

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
-
 import { Command } from 'commander';
 import { run } from '../index.js';
 
+/**
+ * Parses CLI arguments and runs the environment file generator.
+ *
+ * Expects `--map` and `--envfile` options to be provided, with an optional `--profile` for AWS CLI profile selection. Invokes the main process to generate a `.env` file from AWS SSM parameters based on the provided mapping.
+ *
+ * @throws {Error} If either `--map` or `--envfile` arguments are missing.
+ */
 export async function cliRunner() {
   const program = new Command();
 
@@ -11,7 +17,8 @@ export async function cliRunner() {
     .description('A CLI tool to generate .env files from AWS SSM parameters')
     .version('0.1.0')
     .requiredOption('--map <path>', 'Path to the JSON file with environment variable mapping')
-    .requiredOption('--envfile <path>', 'Path to the .env file to be generated');
+    .requiredOption('--envfile <path>', 'Path to the .env file to be generated')
+    .option('--profile <name>', 'AWS CLI profile to use');
 
   await program.parseAsync(process.argv);
   const options = program.opts();
@@ -20,7 +27,7 @@ export async function cliRunner() {
     throw new Error('Missing required arguments: --map and --envfile');
   }
 
-  await run(options.map, options.envfile);
+  await run(options.map, options.envfile, options.profile);
 }
 
 cliRunner().catch((error) => {

package/src/index.ts

@@ -1,14 +1,26 @@
 import * as fs from 'node:fs';
 import { GetParameterCommand, SSM } from '@aws-sdk/client-ssm';
+import { fromIni } from '@aws-sdk/credential-providers';
 import * as dotenv from 'dotenv';
 
-const ssm = new SSM({});
+/**
+ * Orchestrates the process of fetching environment variable values from AWS SSM Parameter Store and writing them to a local environment file.
+ *
+ * Loads a parameter mapping from a JSON file, retrieves existing environment variables, fetches updated values from SSM (optionally using a specified AWS profile), merges them, and writes the result to the specified environment file.
+ *
+ * @param mapPath - Path to the JSON file mapping environment variable names to SSM parameter names.
+ * @param envFilePath - Path to the local environment file to read and update.
+ * @param profile - Optional AWS profile name to use for credentials.
+ */
+export async function run(mapPath: string, envFilePath: string, profile?: string) {
+  const defaultAwsConfig = {};
+  const ssmClientConfig = profile ? { credentials: fromIni({ profile }) } : defaultAwsConfig;
+  const ssm = new SSM(ssmClientConfig);
 
-export async function run(mapPath: string, envFilePath: string) {
   const paramMap = loadParamMap(mapPath);
   const existingEnvVariables = loadExistingEnvVariables(envFilePath);
 
-  const updatedEnvVariables = await fetchAndUpdateEnvVariables(paramMap, existingEnvVariables);
+  const updatedEnvVariables = await fetchAndUpdateEnvVariables(paramMap, existingEnvVariables, ssm);
 
   writeEnvFile(envFilePath, updatedEnvVariables);
   console.log(`Environment File generated at '${envFilePath}'`);
@@ -36,15 +48,28 @@ function loadExistingEnvVariables(envFilePath: string): Record<string, string> {
   return envVariables;
 }
 
+/**
+ * Fetches parameter values from AWS SSM for each environment variable in the map and updates the existing environment variables record.
+ *
+ * For each mapping, retrieves the corresponding SSM parameter value and updates the environment variable if found. Logs masked values and warnings for missing parameters. Throws an error if any parameters fail to fetch.
+ *
+ * @param paramMap - Mapping of environment variable names to SSM parameter names.
+ * @param existingEnvVariables - Current environment variables to be updated.
+ * @param ssm - AWS SSM client instance used for fetching parameters.
+ * @returns The updated environment variables record.
+ *
+ * @throws {Error} If any SSM parameters cannot be fetched.
+ */
 async function fetchAndUpdateEnvVariables(
   paramMap: Record<string, string>,
   existingEnvVariables: Record<string, string>,
+  ssm: SSM,
 ): Promise<Record<string, string>> {
   const errors: string[] = [];
 
   for (const [envVar, ssmName] of Object.entries(paramMap)) {
     try {
-      const value = await fetchSSMParameter(ssmName);
+      const value = await fetchSSMParameter(ssmName, ssm);
       if (value) {
         existingEnvVariables[envVar] = value;
         console.log(
@@ -66,7 +91,13 @@ async function fetchAndUpdateEnvVariables(
   return existingEnvVariables;
 }
 
-async function fetchSSMParameter(ssmName: string): Promise<string | undefined> {
+/**
+ * Retrieves the value of a parameter from AWS SSM Parameter Store with decryption enabled.
+ *
+ * @param ssmName - The name of the SSM parameter to retrieve.
+ * @returns The decrypted parameter value if found, or undefined if the parameter does not exist.
+ */
+async function fetchSSMParameter(ssmName: string, ssm: SSM): Promise<string | undefined> {
   const command = new GetParameterCommand({
     Name: ssmName,
     WithDecryption: true,

package/tests/cli/cliRunner.test.ts

@@ -12,9 +12,9 @@ describe('cliRunner', () => {
   beforeEach(() => {
     process.argv = [...originalArgv.slice(0, 2)];
   });
-
   afterEach(() => {
     vi.clearAllMocks();
+    process.argv = originalArgv;
   });
 
   it('Should_CallRunWithCorrectArguments_When_ValidArgumentsAreProvided', async () => {
@@ -27,7 +27,7 @@ describe('cliRunner', () => {
     await cliRunner();
 
     // Assert
-    expect(run).toHaveBeenCalledWith(mockMapPath, mockEnvFilePath);
+    expect(run).toHaveBeenCalledWith(mockMapPath, mockEnvFilePath, undefined);
   });
 
   it('Should_ThrowError_When_RequiredArgumentsAreMissing', async () => {
@@ -42,4 +42,18 @@ describe('cliRunner', () => {
     // Assert
     await expect(action).rejects.toThrow('process.exit called');
   });
+
+  it('Should_CallRunWithCorrectArgumentsIncludingProfile_When_ProfileIsProvided', async () => {
+    // Arrange
+    const mockMapPath = 'path/to/mockMap.json';
+    const mockEnvFilePath = 'path/to/.env';
+    const mockProfile = 'test-profile';
+    process.argv.push('--map', mockMapPath, '--envfile', mockEnvFilePath, '--profile', mockProfile);
+
+    // Act
+    await cliRunner();
+
+    // Assert
+    expect(run).toHaveBeenCalledWith(mockMapPath, mockEnvFilePath, mockProfile);
+  });
 });