switch-profile 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.2.1](https://github.com/nicolasdao/switch-profile/compare/v0.2.0...v0.2.1) (2026-02-08)
+
+## [0.2.0](https://github.com/nicolasdao/switch-profile/compare/v0.1.2...v0.2.0) (2026-02-08)
+
+
+### Bug Fixes
+
+* handle SSO profile creation failure and improve SSO setup UX ([b0ee837](https://github.com/nicolasdao/switch-profile/commit/b0ee83791bfbc1208cc5fb6b6f2850d4cbd160c9))
+* vulnerabilities ([3fa2575](https://github.com/nicolasdao/switch-profile/commit/3fa2575156f3e07a6de9cd077f3f8f75f9bceafa))
+
+### [0.1.2](https://github.com/nicolasdao/switch-profile/compare/v0.1.1...v0.1.2) (2022-05-14)
+
+
+### Bug Fixes
+
+* Multiple SSO profiles are not supported. It only uses one. ([b9d9d03](https://github.com/nicolasdao/switch-profile/commit/b9d9d03b4edfa048cc157376222378513138e257))
+
 ### [0.1.1](https://github.com/nicolasdao/switch-profile/compare/v0.1.0...v0.1.1) (2021-08-03)
 
 

package/README.md

@@ -1,43 +1,157 @@
 # switch-profile
 
-Switch between AWS profiles without having to manually edit the `.aws/credentials` or the environment variables. 
+An interactive CLI tool for switching between AWS profiles directly from your terminal. No more manually editing `~/.aws/credentials` or juggling environment variables.
 
+```shell
+npx switch-profile
+```
+
+## Why?
+
+AWS SSO credentials expire every hour. Without `switch-profile`, refreshing them means either:
+
+1. **Manual copy-paste** - Browse to the SSO portal, log in, reveal credentials, paste them into your terminal or `~/.aws/credentials` file. Repeat every hour.
+2. **Per-command `--profile` flag** - Use `aws sso login --profile <name>`, but then every command (and every tool like Terraform) needs `--profile`. Not always possible or practical.
+
+`switch-profile` makes setting any AWS profile as `default` trivial - one command, pick from a list, done. It handles SSO session refresh automatically, including opening the browser for re-authentication when sessions expire.
+
+## Prerequisites
+
+- **[AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)** - Version 2 or later is required.
+- **Node.js** - Any recent version that supports `npx`.
+
+> **Important:** Remove these environment variables from your shell if they are set, as they override the default profile and will conflict with `switch-profile`:
+> - `AWS_ACCESS_KEY_ID`
+> - `AWS_SECRET_ACCESS_KEY`
+> - `AWS_SESSION_TOKEN`
+
+## Installation
+
+No installation needed. Run directly with npx:
+
+```shell
+npx switch-profile
+```
+
+Or install globally:
+
+```shell
+npm install -g switch-profile
+switch-profile
+```
+
+## Quick Start
+
+### Switch between existing profiles
+
+```shell
+npx switch-profile
+```
+
+This will:
+1. Show your current default profile with its expiry status.
+2. List all available profiles.
+3. Let you pick one to set as the new `default`.
+
+For SSO profiles, if the session has expired, it automatically opens your browser for re-authentication.
+
+### Create a new profile
+
+```shell
+npx switch-profile
+# Select "More options" > "Create profile"
 ```
+
+You can create:
+- **Standard profiles** - Access key + secret key pair.
+- **SSO profiles** - Launches the interactive `aws configure sso` flow.
+
+### Delete profiles
+
+```shell
 npx switch-profile
+# Select "More options" > "Delete profiles"
 ```
 
-This terminal utility helps switching between AWS CLI profiles. It sets the `default` profile by editing the `.aws/credentials` file. It requires `AWS CLI v2` to be installed. 
+Select one or more profiles to remove. The current default profile cannot be deleted (switch to another one first).
+
+### Refresh an expired profile
+
+```shell
+npx switch-profile
+# Select "More options" > "Refresh default profile"
+```
+
+This option only appears when the current default profile has expired. It forces a new SSO login and refreshes the credentials.
+
+## How It Works
+
+`switch-profile` manages two AWS configuration files:
+
+| File | Purpose |
+|------|---------|
+| `~/.aws/config` | Stores profile settings (region, output format, SSO metadata) |
+| `~/.aws/credentials` | Stores access keys, secret keys, and session tokens |
 
-This utility also supports creating new AWS profiles, including SSO profiles as well as deleting them. 
+When you select a profile, `switch-profile`:
+1. Retrieves the credentials for that profile (from cache or via SSO login).
+2. Writes them into the `[default]` section of both files.
+3. Records the profile name and expiry date for status display.
 
-> WARNING: Make sure that the following environment variables have been removed from your path, otherwise, they will conflict with the default AWS CLI profile:
->	- `AWS_ACCESS_KEY_ID`
->	- `AWS_SECRET_ACCESS_KEY`
->	- `AWS_SESSION_TOKEN`
+For SSO profiles specifically, it leverages two additional AWS CLI cache directories:
+- `~/.aws/sso/cache/` - SSO session tokens (long-lived, ~24 hours)
+- `~/.aws/cli/cache/` - Temporary AWS credentials (short-lived, ~1 hour)
 
-# Why using this utility?
+## Detailed Documentation
 
-`switch-profile` was originally created to refresh short-lived AWS SSO profiles in the terminal and set them as default. Indeed, as of 2021, the only two ways to set up a short-lived SSO profile as default in the terminal are:
-- Manually paste the short-lived credentials in the terminal:
-	- Browse to the AWS SSO login page and login. 
-	- Select an account.
-	- Reveal the short-lived credentials (i.e., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN).
-	- Copy paste them in the terminal or manually edit the `.aws/credentials` file.
-- Create an SSO profile in the terminal and update its credentials via the CLI:
-	- Creating an SSO profile: `aws configure sso`
-	- Renew a SSO credentials for a specific profile: `aws sso login --profile YOUR_PROFILE`
+For deeper technical details, see the docs below:
 
-The issue with the first method is that you have to repeat it every hour, which can make long days feel even longer. The issue with the second method is that it requires your code or third party app (e.g, Terraform) to support the `--profile` option. There are scenarios where using this `--profile` option is either not possible or impractical (often impractical as this may mean all engineers should agree to use the same convention for the profile's name).
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/architecture.md) | Project structure, source files, and how the components fit together |
+| [AWS Profile Management](docs/aws-profile-management.md) | How AWS profiles, SSO sessions, and credentials are managed internally |
+| [CLI Interface](docs/cli-interface.md) | Detailed walkthrough of every menu, prompt, and user flow |
+| [Configuration Files](docs/configuration-files.md) | Exact formats of all AWS and internal configuration files |
+| [Development Guide](docs/development-guide.md) | How to set up, develop, test, lint, and release |
 
-`switch-profile` aims to solve those issues by making setting any profile as `default` trivial. 
+## Troubleshooting
 
-# Extra features
+### `invalid_grant: Invalid grant provided`
+
+This error occurs during SSO profile creation when the **wrong SSO region** is specified. AWS SSO is region-specific - you must use the region where your SSO instance is configured, not the region you want to deploy resources to.
+
+**Fix:** Delete the profile and recreate it with the correct SSO region.
+
+### `Error: Fail to get credentials for profile ... Error loading SSO Token...`
+
+This typically happens after the `~/.aws/sso/cache` folder has been deleted or corrupted. This folder tracks SSO sessions and cannot be reconstructed automatically.
+
+**Fix:** Delete the affected SSO profiles and recreate them:
+
+1. Run `npx switch-profile`
+2. Select **More options** > **Delete profiles**
+3. Remove the broken SSO profiles
+4. Recreate them via **More options** > **Create profile**
+
+### AWS CLI not found
+
+`switch-profile` requires AWS CLI v2. Install it for your platform:
+
+**macOS:**
+```shell
+brew install awscli
+brew link --overwrite awscli
+```
+
+**Linux:**
+```shell
+curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+unzip awscliv2.zip
+sudo ./aws/install
+```
 
-The `More options` supports the following:
-- `Create profile`: Helps create both a standard or AWS SSO profile.
-- `Delete profiles`: Helps cleaning one or many profiles.
-- `Refresh default profile`: Helps refreshing the current default profile if it has expired (e.g., SSO profile). This option only appears when the default profile has expired.
+**Windows:** Download and run the [AWS CLI MSI installer](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
 
-# License
+## License
 
-BSD 3-Clause License
+[BSD 3-Clause](LICENSE)

package/docs/architecture.md

@@ -0,0 +1,185 @@
+# Architecture
+
+This document describes the project structure, source files, and how the components fit together.
+
+## Project Structure
+
+```
+switch-profile/
+├── index.js                  # CLI entry point (executable)
+├── package.json              # Project manifest
+├── CHANGELOG.md              # Auto-generated release notes
+├── LICENSE                   # BSD 3-Clause
+├── src/
+│   ├── core.js               # Shell execution and error formatting
+│   ├── fileHelper.js         # File system operations
+│   └── aws/
+│       ├── index.js          # AWS profile and credential management
+│       └── regions.js        # AWS region definitions
+└── test/
+    └── index.js              # Test suite
+```
+
+## Component Overview
+
+### `index.js` - CLI Entry Point
+
+The main executable file (with `#!/usr/bin/env node` shebang). Registered as the `bin` target in `package.json`, so it runs when you invoke `switch-profile` or `npx switch-profile`.
+
+**Responsibilities:**
+- Defines the CLI command structure using [Commander.js](https://www.npmjs.com/package/commander).
+- Renders interactive prompts using [Inquirer.js](https://www.npmjs.com/package/inquirer).
+- Orchestrates the user flow: profile listing, selection, creation, deletion, and refresh.
+- Displays colored status output (expiry warnings, success messages).
+
+**Key functions:**
+
+| Function | Purpose |
+|----------|---------|
+| `switchCmd()` | Main command handler. Checks AWS CLI, shows current profile status, lists profiles, renders the selection menu. |
+| `setProfileToDefault(name, list, msg)` | Gets credentials for a profile, writes them as the `[default]` profile. Shows a clear error if the profile is not found in the list. |
+| `createNewProfile(profiles, makeItDefault)` | Walks the user through creating a standard or SSO profile. Displays an SSO Setup Guide before SSO creation and checks for errors before reporting success. |
+| `chooseProfileName(denyList)` | Validates profile name input (lowercase alphanumeric, dashes, underscores, min 2 chars, no duplicates). |
+| `chooseRegions()` | Autocomplete region picker from the 24 supported AWS regions. |
+| `chooseNonEmpty(prop, message)` | Generic required-field input validator. |
+
+**Default command behavior:** If no command is passed (`process.argv.length == 2`), it automatically injects the `switch` command.
+
+### `src/aws/index.js` - AWS Profile Management
+
+The core module. Handles all interactions with AWS configuration files and the AWS CLI.
+
+**Responsibilities:**
+- Reading and writing `~/.aws/config` and `~/.aws/credentials`.
+- Parsing INI-style profile sections.
+- Managing SSO sessions and credential caching.
+- Creating, deleting, and listing profiles.
+- Refreshing expired SSO sessions (including browser redirect).
+
+See [AWS Profile Management](aws-profile-management.md) for a detailed breakdown of every function.
+
+### `src/aws/regions.js` - Region Definitions
+
+A static array of 24 AWS region objects, each with `name` and `code` properties:
+
+```javascript
+{ name: 'US East (N. Virginia)', code: 'us-east-1' }
+```
+
+Regions covered: 4 US, 8 Asia Pacific, 6 EU, 2 China, 2 GovCloud, 1 Africa, 1 Canada, 1 Middle East, 1 South America.
+
+### `src/core.js` - Shell Execution and Error Formatting
+
+Low-level utilities shared across the project.
+
+| Function | Purpose |
+|----------|---------|
+| `exec(cmd)` | Wraps `child_process.exec()` in a Promise. Rejects on error or stderr. |
+| `isCommandExist(cmd, errorMsg)` | Returns a function that checks if `cmd` exists in PATH (uses `which` on Unix, `where` on Windows). Results are cached. |
+| `printErrors(errors, options)` | Prints an array of `Error` objects in red. |
+| `printAWSerrors(errors, options)` | Like `printErrors` but detects missing AWS CLI and appends installation hints. |
+| `formatErrorMsg(errors, options)` | Formats error arrays into a single message string. Supports `noStack` option. |
+
+### `src/fileHelper.js` - File System Operations
+
+A general-purpose file I/O library. Only a subset of its functions are used by `switch-profile`:
+
+**Used by the project:**
+
+| Function | Exported As | Purpose |
+|----------|-------------|---------|
+| `fileExists(path)` | `exists` | Check if a file or folder exists |
+| `readFile(path)` | `read` | Read file contents into a Buffer |
+| `writeToFile(path, content, opts)` | `write` | Create or overwrite a file |
+| `listFiles(folder, opts)` | `list` | Glob-based file listing |
+| `getJSON(path, default)` | `json.get` | Read and parse a JSON file |
+
+**Available but unused:**
+
+Functions for folder creation/deletion, MIME type detection, ZIP/TAR archiving, and more. These exist because `fileHelper.js` is a shared utility library.
+
+## Dependency Graph
+
+```
+index.js
+├── commander          (CLI framework)
+├── inquirer           (interactive prompts)
+├── inquirer-autocomplete-prompt
+├── colors             (terminal colors)
+├── src/core.js
+│   ├── colors
+│   ├── puffy          (error handling: catchErrors, wrapErrors)
+│   └── child_process  (Node built-in)
+├── src/aws/index.js
+│   ├── puffy          (error handling + delay)
+│   ├── src/core.js
+│   ├── src/fileHelper.js
+│   │   ├── core-async (co-routine support)
+│   │   ├── fast-glob  (file pattern matching)
+│   │   ├── rimraf     (recursive delete)
+│   │   ├── mime-types (MIME detection)
+│   │   ├── archiver   (ZIP creation - unused)
+│   │   ├── tar-stream (TAR creation - unused)
+│   │   └── convert-stream (stream utils - unused)
+│   ├── src/aws/regions.js
+│   └── child_process  (for spawn)
+└── package.json       (version number)
+```
+
+## Error Handling Pattern
+
+All async functions in the AWS module use the `catchErrors` wrapper from the `puffy` library. This converts thrown errors into a `[errors, result]` tuple:
+
+```javascript
+const [errors, profiles] = await listProfiles()
+if (errors) {
+    printAWSerrors([new Error('Fail to list profiles'), ...errors])
+    return
+}
+// Use profiles safely
+```
+
+Errors are composed using `wrapErrors(message, errorArray)` to build layered error contexts:
+
+```
+Error: Fail to get credentials for profile sso-dev
+  → Error: Fail to refresh the SSO session
+    → Error: Timeout - Time to wait exceeded 300000ms
+```
+
+This pattern allows errors to propagate up with context while keeping individual functions simple.
+
+## Data Flow
+
+```
+User runs: npx switch-profile
+                │
+                ▼
+        ┌──────────────┐
+        │   index.js   │  Checks AWS CLI v2 exists
+        │  switchCmd()  │  Gets default profile + status
+        │              │  Lists all profiles
+        └──────┬───────┘
+               │
+               ▼
+        User selects a profile
+               │
+               ▼
+    ┌──────────────────────┐
+    │  setProfileToDefault │
+    │                      │
+    │  1. Find profile     │
+    │  2. Get credentials  │──────► For SSO: refresh session,
+    │  3. Update default   │        open browser if needed
+    └──────────────────────┘
+               │
+               ▼
+    ┌──────────────────────┐
+    │  updateDefaultProfile│
+    │                      │
+    │  Writes [default]    │
+    │  section to:         │
+    │  - ~/.aws/credentials│
+    │  - ~/.aws/config     │
+    └──────────────────────┘
+```