switch-profile 1.1.0 → 2.0.1

package/docs/cli-interface.md

@@ -1,304 +0,0 @@
-# CLI Interface
-
-This document provides a detailed walkthrough of every menu, prompt, and user flow in `switch-profile`.
-
-## Invocation
-
-```shell
-npx switch-profile          # Run via npx (no install)
-switch-profile              # If installed globally
-npx switch-profile switch   # Explicit command (same as default)
-npx switch-profile --version  # Print version number
-```
-
-The `switch` command is the only command and runs automatically when no arguments are provided.
-
-## Main Flow
-
-### Step 1: AWS CLI Check
-
-Before anything else, the tool verifies AWS CLI v2+ is installed. If not found, it prints platform-specific installation instructions:
-
-- **macOS:** `brew install awscli && brew link --overwrite awscli`
-- **Linux:** curl + unzip instructions for the AWS CLI v2 installer
-- **Windows:** "Not installed" message with a link to the AWS CLI MSI installer download page
-
-### Step 2: Default Profile Status
-
-If a default profile is set, it displays the current status with color-coded information:
-
-```
-Current default profile: sso-dev
- INFO: This profile expires in 45.23 minutes     # Cyan - healthy
-```
-
-```
-Current default profile: sso-dev
- WARNING: Expires in less than 2 minutes          # Yellow - expiring soon
-```
-
-```
-Current default profile: sso-dev
- WARNING: Expired                                 # Yellow - expired
-```
-
-```
-Current default profile: unknown (pick one up in the list below...)  # No profile set
-```
-
-The expiry time is calculated in minutes to two decimal places.
-
-### Step 3: Profile List
-
-If profiles exist, the main selection menu appears:
-
-```
-? Choose one of the following 3 profiles:
-  More options
-  Abort
-  ──────────────
-  1. sso-dev (SSO [role:Admin - account:123456789012])
-  2. sso-prod (SSO [role:ReadOnly - account:987654321098])
-  3. my-standard-profile
-```
-
-- **SSO profiles** include role and account info in their display name.
-- **Standard profiles** show just the profile name.
-- The list supports up to 20 items per page.
-
-If no profiles exist, you get:
-
-```
-? There no profiles yet. Do you wish to create one now? (Y/n)
-```
-
-### Step 4a: Select a Profile
-
-Selecting a profile from the list sets it as the `default`. For SSO profiles, this may:
-
-1. Open your browser for SSO authentication (if the session expired).
-2. Wait for you to complete the login (up to 5 minutes).
-3. Retrieve temporary credentials from the AWS CLI cache.
-
-On success:
-
-**Linux / macOS:**
-```
-AWS profile sso-dev successfully set up as default.   # Green
-
-┌─────────────────────────────────────────────────────────┐
-│  To lock this profile to this terminal session, run:    │  # Cyan
-│                                                         │
-│    export AWS_PROFILE=sso-dev                           │  # Cyan + Bold
-│                                                         │
-│  This prevents other terminals from affecting this one. │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Windows:**
-```
-AWS profile sso-dev successfully set up as default.   # Green
-
-┌──────────────────────────────────────────────────────────────┐
-│  To lock this profile to this terminal session, run:         │  # Cyan
-│                                                              │
-│    PowerShell:  $env:AWS_PROFILE = "sso-dev"                 │  # Cyan + Bold
-│    CMD:         set AWS_PROFILE=sso-dev                      │  # Cyan + Bold
-│                                                              │
-│  This prevents other terminals from affecting this one.      │
-└──────────────────────────────────────────────────────────────┘
-```
-
-This hint appears after every successful profile switch, refresh, or new profile set as default. Running the displayed command sets the `AWS_PROFILE` environment variable in the current terminal only, enabling per-terminal profile isolation.
-
-### Step 4b: More Options
-
-Selecting "More options" opens a submenu:
-
-```
-? Options:
-  Refresh default profile sso-dev    # Only shown when expired
-  Create profile
-  Delete profiles
-  Abort
-```
-
-## Create Profile Flow
-
-### Step 1: Profile Name
-
-```
-? Enter a profile name (alphanumerical lowercase and '-' characters only):
-```
-
-**Validation rules:**
-- Cannot be empty.
-- Only lowercase letters, numbers, dashes (`-`), and underscores (`_`).
-- Minimum 2 characters.
-- Cannot duplicate an existing profile name.
-
-Invalid input produces a red error and re-prompts.
-
-### Step 2: Profile Type
-
-```
-? Choose an AWS profile type:
-  standard
-  sso
-```
-
-### Step 3a: Standard Profile
-
-```
-? Enter the profile's access key: AKIA...
-? Enter the profile's access secret key: wJal...
-? Select a region: (type to search)
-  us-east-2 - US East (Ohio)
-  us-east-1 - US East (N. Virginia)
-  us-west-1 - US West (N. California)
-  ...
-```
-
-The region picker supports autocomplete - type to filter the list of 24 regions.
-
-### Step 3b: SSO Profile
-
-Selecting "sso" first displays an SSO Setup Guide with guidance on the prompts you're about to see:
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                     SSO Profile Setup Guide                         │
-├─────────────────────────────────────────────────────────────────────┤
-│                                                                     │
-│  You're about to run 'aws configure sso'. Here's what to expect:    │
-│                                                                     │
-│  1. SSO session name                                                │
-│     Provide a name (e.g., "my-company-sso").                        │
-│     This enables token reuse across profiles and automatic refresh.  │
-│     Skipping this uses the legacy format (no auto-refresh).          │
-│                                                                     │
-│  2. SSO start URL                                                   │
-│     Your AWS SSO portal URL (e.g., https://my-co.awsapps.com/start) │
-│     Ask your AWS administrator if you don't have it.                 │
-│                                                                     │
-│  3. SSO region                                                      │
-│     The region where your SSO instance is configured.                │
-│     WARNING: This is NOT your deployment region.                     │
-│     Using the wrong region causes "invalid_grant" errors.            │
-│                                                                     │
-│  Docs: https://docs.aws.amazon.com/cli/latest/userguide/            │
-│        cli-configure-sso.html                                       │
-│                                                                     │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-Then it spawns the interactive `aws configure sso` command, which takes over the terminal:
-
-```
-SSO session name (Recommended): my-session
-SSO start URL [None]: https://my-company.awsapps.com/start
-SSO region [None]: us-east-1
-SSO registration scopes [sso:account:access]:
-...
-```
-
-This is the standard AWS CLI SSO setup flow. The user completes it directly. If the `aws configure sso` command fails (non-zero exit code), the error is reported and the profile is not marked as created.
-
-### Step 4: Set as Default
-
-After creation, you're asked:
-
-```
-? Do you wish to set this new profile as the default? (Y/n)
-```
-
-If yes, the profile is immediately set as the `default` (triggering SSO login if needed). If the profile is not found in `~/.aws/config` (e.g., because the creation partially failed), a clear error message is shown instead of crashing.
-
-## Delete Profiles Flow
-
-### Step 1: Select Profiles
-
-```
-? Select the profiles you which to delete:
-  ◯ 1. sso-dev (SSO [role:Admin - account:123456789012])
-  ◯ 2. sso-prod (SSO [role:ReadOnly - account:987654321098])
-  ◯ 3. my-standard-profile
-```
-
-This is a checkbox selection - you can select multiple profiles.
-
-### Step 2: Confirmation
-
-```
-? Are you sure you want to delete those 2 profiles? (Y/n)
-```
-
-### Step 3: Validation
-
-If you try to delete the current default profile:
-
-```
-ERROR - Fail to delete profiles. Profile sso-dev is the current default.
-Set another profile as the default, then try deleting again.
-```
-
-You must switch to a different profile first.
-
-### Step 4: Success
-
-```
-AWS profiles successfully deleted.    # Green
-```
-
-## Refresh Default Profile
-
-This option only appears in the "More options" submenu when the current default profile is expired.
-
-Selecting it:
-1. Looks up the current default profile in the profile list.
-2. Retrieves fresh credentials (SSO login if needed).
-3. Updates the `[default]` section.
-
-**Linux / macOS:**
-```
-AWS profile sso-dev successfully refreshed.    # Green
-
-┌─────────────────────────────────────────────────────────┐
-│  To lock this profile to this terminal session, run:    │  # Cyan
-│                                                         │
-│    export AWS_PROFILE=sso-dev                           │  # Cyan + Bold
-│                                                         │
-│  This prevents other terminals from affecting this one. │
-└─────────────────────────────────────────────────────────┘
-```
-
-On Windows, the hint shows PowerShell and CMD equivalents instead (see [Step 4a](#step-4a-select-a-profile)).
-
-## Visual Indicators
-
-| Color | Meaning |
-|-------|---------|
-| **Green** | Success messages |
-| **Red** | Error messages |
-| **Cyan** | Informational (current profile, time remaining) |
-| **Yellow** | Warnings (expired, expiring soon) |
-| **Bold** | Profile names in messages |
-| **Cyan + Bold** | Profile isolation command hint (`export AWS_PROFILE=...` on Unix, PowerShell/CMD equivalents on Windows) |
-
-## Error Display
-
-Errors are displayed in red with contextual messages:
-
-```
-ERROR - Fail to get credentials for profile sso-dev
-Fail to refresh the SSO session for AWS profile sso-dev
-Timeout - Time to wait for refreshing the SSO session exceeded 300000ms.
-```
-
-When the AWS CLI is missing, a helpful suggestion is appended:
-
-```
-ERROR - Command aws not found
-
-To fix this issue, try installing the aws CLI
-```

package/docs/configuration-files.md

@@ -1,240 +0,0 @@
-# Configuration Files
-
-This document describes the exact format of all AWS configuration files that `switch-profile` reads and writes.
-
-## `~/.aws/config`
-
-The AWS CLI configuration file. Stores profile settings including region, output format, and SSO metadata.
-
-### Format
-
-Standard INI-style format. The default profile uses `[default]`, all other profiles use `[profile name]`.
-
-### Example
-
-```ini
-[default]
-region = us-east-1
-output = json
-
-[profile my-standard]
-region = ap-southeast-2
-output = json
-
-[profile sso-dev]
-sso_start_url = https://my-company.awsapps.com/start
-sso_region = us-east-1
-sso_account_id = 123456789012
-sso_role_name = CloudlessAdmin
-region = us-east-1
-output = json
-```
-
-### Fields
-
-**Standard profile fields:**
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `region` | AWS region for API calls | `us-east-1` |
-| `output` | CLI output format | `json` |
-
-**SSO profile additional fields:**
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `sso_start_url` | SSO portal URL | `https://my-company.awsapps.com/start` |
-| `sso_region` | Region where SSO is configured | `us-east-1` |
-| `sso_account_id` | AWS account ID (12 digits) | `123456789012` |
-| `sso_role_name` | IAM role name in the account | `CloudlessAdmin` |
-
-### How `switch-profile` Modifies This File
-
-When setting a profile as default, only the `[default]` section is updated (region and output). Other profile sections are preserved unchanged.
-
-When creating a standard profile, a new `[profile name]` section is appended. When creating an SSO profile, the `aws configure sso` command writes the section.
-
-When deleting a profile, the `[profile name]` section and its contents (up to the next `[` bracket) are removed via regex.
-
----
-
-## `~/.aws/credentials`
-
-Stores AWS access credentials. All profiles use `[name]` syntax (no `profile` prefix).
-
-### Example
-
-```ini
-[default]
-aws_access_key_id = ASIAZOCWXABCD123456
-aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-aws_session_token = AQoDYXdzEJr...
-expiry_date = 2021-07-17T11:33:12.000Z
-profile = sso-dev
-
-[my-standard]
-aws_access_key_id = AKIAIOSFODNN7EXAMPLE
-aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-```
-
-### Standard AWS Fields
-
-| Field | Description | Present For |
-|-------|-------------|-------------|
-| `aws_access_key_id` | AWS access key | All profiles |
-| `aws_secret_access_key` | AWS secret key | All profiles |
-| `aws_session_token` | Temporary session token | SSO profiles only |
-
-### Custom Fields (added by `switch-profile`)
-
-These fields are written into the `[default]` section only:
-
-| Field | Description | Purpose |
-|-------|-------------|---------|
-| `profile` | Name of the profile these credentials belong to | Track which profile is currently active |
-| `expiry_date` | ISO 8601 timestamp of when credentials expire | Display expiry status, detect expired profiles |
-
-These are non-standard fields. The AWS CLI ignores them, but `switch-profile` reads them back to show profile status.
-
-### How `switch-profile` Modifies This File
-
-When setting a profile as default, the `[default]` section is replaced with the selected profile's credentials plus the custom `profile` and `expiry_date` fields.
-
-When creating a standard profile, a new `[name]` section with access key and secret key is appended.
-
-When deleting a profile, the `[name]` section and its contents are removed via regex.
-
----
-
-## `~/.aws/sso/cache/` (Read-only)
-
-`switch-profile` reads but does not write to this directory. It is managed entirely by the AWS CLI.
-
-### Purpose
-
-Stores SSO session tokens obtained through the `aws sso login` flow.
-
-### File Format
-
-Files are named with hash-based identifiers (e.g., `bdc1be3a4f0c3b5e8c0e4d6a1b2c3d4e.json`).
-
-```json
-{
-    "startUrl": "https://my-company.awsapps.com/start",
-    "region": "us-east-1",
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "expiresAt": "2021-07-17T11:33:12Z"
-}
-```
-
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `startUrl` | The SSO portal URL this session belongs to |
-| `region` | The SSO region |
-| `accessToken` | JWT token for the SSO session |
-| `expiresAt` | ISO 8601 expiry timestamp |
-
-### How `switch-profile` Uses It
-
-The tool searches all `*.json` files in this directory when it needs to verify or find an SSO session. It matches by comparing the `startUrl` host with the profile's `sso_start_url` host. A session is considered valid if it expires more than 2 minutes from now.
-
----
-
-## `~/.aws/cli/cache/` (Read-only)
-
-`switch-profile` reads but does not write to this directory. It is managed entirely by the AWS CLI.
-
-### Purpose
-
-Stores temporary AWS credentials (access key, secret key, session token) obtained through SSO authentication.
-
-### File Format
-
-Files are named with hash-based identifiers.
-
-```json
-{
-    "ProviderType": "sso",
-    "Credentials": {
-        "AccessKeyId": "ASIAZOCWXABCD123456",
-        "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
-        "SessionToken": "AQoDYXdzEJr...",
-        "Expiration": "2021-07-17T11:33:12Z"
-    }
-}
-```
-
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `ProviderType` | Credential source type (`"sso"` for SSO) |
-| `Credentials.AccessKeyId` | AWS access key ID |
-| `Credentials.SecretAccessKey` | AWS secret access key |
-| `Credentials.SessionToken` | Temporary session token |
-| `Credentials.Expiration` | ISO 8601 expiry timestamp |
-
-### How `switch-profile` Uses It
-
-After running `aws configure list --profile <name>` (which populates this cache), the tool searches for a file where:
-
-1. `ProviderType` is `"sso"`.
-2. The last 4 characters of `AccessKeyId` match what `aws configure list` reported.
-3. The last 4 characters of `SecretAccessKey` match what `aws configure list` reported.
-4. `Expiration` is at least 2 minutes in the future.
-
-This matching-by-suffix approach is necessary because `aws configure list` only shows masked keys (e.g., `****3456`), not the full values.
-
----
-
-## Default File Contents
-
-When `switch-profile` creates a standard profile and the AWS config files don't exist yet, it initializes them with these defaults:
-
-**`~/.aws/config`:**
-```ini
-[default]
-region = ap-southeast-1
-output = json
-
-```
-
-**`~/.aws/credentials`:**
-```ini
-[default]
-aws_access_key_id = 1234_DUMMY
-aws_secret_access_key = 4567_DUMMY
-
-```
-
-These are dummy values that serve as placeholders until a real profile is set as default.
-
----
-
-## INI Parsing Approach
-
-`switch-profile` does not use a dedicated INI parser. Instead, it uses regex-based string operations:
-
-**Reading a section:**
-```javascript
-// Extract [default] section content (everything until the next [ or end of file)
-const section = fileContent.match(/\[default\]((.|\n|\r)*?)(\[|$)/)[0]
-```
-
-**Extracting a parameter:**
-```javascript
-// Match "  paramName = value" with flexible whitespace
-const regexp = new RegExp(`\\s*${paramName}\\s*=\\s*`)
-const value = params.filter(p => regexp.test(p)).map(p => p.replace(regexp,'').trim())[0]
-```
-
-**Replacing a section:**
-```javascript
-// Replace the [default] section while preserving the opening bracket of the next section
-const lastChar = defaultSection.slice(-1)  // Either '[' or end-of-string
-updatedContent = fileContent.replace(defaultSection, newSection + lastChar)
-```
-
-This approach works for the tool's use case but depends on well-formed config files. It preserves all content outside the targeted section unchanged.

package/docs/development-guide.md

@@ -1,168 +0,0 @@
-# Development Guide
-
-This document covers how to set up, develop, test, lint, and release `switch-profile`.
-
-## Setup
-
-```shell
-git clone https://github.com/nicolasdao/switch-profile.git
-cd switch-profile
-npm install
-```
-
-## Running Locally
-
-**Development mode:**
-```shell
-npm run dev
-# Runs: TZ=UTC NODE_ENV=dev node index.js
-```
-
-**Production mode:**
-```shell
-npm start
-# Runs: TZ=UTC NODE_ENV=production node index.js
-```
-
-**Direct execution:**
-```shell
-node index.js
-```
-
-Both modes set `TZ=UTC` to ensure consistent timestamp handling.
-
-## Linting
-
-```shell
-npm run lint
-# Runs: eslint index.js src/ test/ --fix
-```
-
-The ESLint configuration (`.eslintrc.json`) enforces:
-
-| Rule | Setting |
-|------|---------|
-| Indentation | Tabs |
-| Quotes | Single |
-| Semicolons | None (never) |
-| Line endings | Unix (`\n`) |
-| Environment | ES6, Node.js (CommonJS) |
-| Console | Allowed |
-
-The `--fix` flag auto-fixes style issues when possible.
-
-## Testing
-
-```shell
-npm test
-# Runs: mocha --exit
-```
-
-Tests are located in `test/index.js` and use [Mocha](https://mochajs.org/) as the test runner and [Chai](https://www.chaijs.com/) for assertions.
-
-**Current state:** The test suite contains a single placeholder test. There are no functional tests for the AWS operations, profile management, or file I/O.
-
-**Test utilities (from comments in test file):**
-- Skip a test: Use `xit` instead of `it`, or `describe.skip` instead of `describe`.
-- Run only one test: Use `it.only` instead of `it`.
-
-## Dependencies
-
-### Production Dependencies
-
-| Package | Purpose |
-|---------|---------|
-| `commander` | CLI argument parsing and command registration |
-| `inquirer` | Interactive prompts (list, input, confirm, checkbox) |
-| `inquirer-autocomplete-prompt` | Autocomplete support for region selection |
-| `colors` | Colored terminal output |
-| `puffy` | Error handling (`catchErrors`, `wrapErrors`, `delay`) |
-| `core-async` | Generator-based async flow (co-routines) |
-| `fast-glob` | File pattern matching for cache directory scanning |
-| `rimraf` | Cross-platform recursive directory deletion |
-| `mime-types` | MIME type detection (used by fileHelper, not core functionality) |
-| `archiver` | ZIP creation (imported by fileHelper, unused in current flows) |
-| `tar-stream` | TAR streaming (imported by fileHelper, unused in current flows) |
-| `convert-stream` | Stream conversion (imported by fileHelper, unused in current flows) |
-
-### Dev Dependencies
-
-| Package | Purpose |
-|---------|---------|
-| `mocha` | Test runner |
-| `chai` | Assertion library |
-| `eslint` | Code linting |
-| `standard-version` | Automated versioning and changelog generation |
-
-### Unused Dependencies
-
-The `fileHelper.js` module is a shared utility library that imports several packages not used by `switch-profile`'s core functionality: `archiver`, `tar-stream`, `convert-stream`, and partially `mime-types`. These are present because `fileHelper.js` provides general-purpose file operations that may be used in other projects sharing this codebase.
-
-## Release Process
-
-### Step 1: Version Bump and Changelog
-
-```shell
-npm run rls -- minor    # For new features (0.1.x → 0.2.0)
-npm run rls -- patch    # For bug fixes (0.1.2 → 0.1.3)
-npm run rls -- major    # For breaking changes (0.x.x → 1.0.0)
-```
-
-This runs `standard-version --release-as <type>`, which:
-1. Bumps the version in `package.json`.
-2. Updates `CHANGELOG.md` based on conventional commit messages.
-3. Creates a git commit with the version bump.
-4. Creates an annotated git tag (e.g., `v0.1.3`).
-
-### Step 2: Publish
-
-```shell
-npm run push
-# Runs: git push --follow-tags origin master && npm publish --access=public
-```
-
-This:
-1. Pushes the commit and tag to the `master` branch on GitHub.
-2. Publishes the package to the npm registry with public access.
-
-### Version Check
-
-```shell
-npm run v
-# Prints the current version from package.json
-```
-
-## npm Package Configuration
-
-| Field | Value |
-|-------|-------|
-| Package name | `switch-profile` |
-| Entry point | `index.js` |
-| Binary | `index.js` (registered via `"bin"` field) |
-| Access | Public |
-| License | BSD-3-Clause |
-| Files excluded from npm | `test/` (via `.npmignore`) |
-
-## Conventional Commits
-
-The project uses [standard-version](https://github.com/conventional-commits/standard-version) for automated changelog generation. Commit messages should follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
-
-```
-feat: Add support for profile refresh
-fix: Multiple SSO profiles are not supported
-chore(release): 0.1.2
-```
-
-Prefixes:
-- `feat:` - New features (bumps minor version)
-- `fix:` - Bug fixes (bumps patch version)
-- `chore:` - Maintenance tasks (no version bump unless specified)
-
-## Project Layout Conventions
-
-- **No semicolons** in JavaScript files.
-- **Tab indentation** throughout.
-- **Single quotes** for strings.
-- **CommonJS** module system (`require`/`module.exports`), not ES modules.
-- **Error tuple pattern**: Async functions return `[errors, result]` via the `catchErrors` wrapper from `puffy`.
-- **Shebang**: `index.js` starts with `#!/usr/bin/env node` for direct CLI execution.