switch-profile 0.1.2 → 0.2.2

package/docs/aws-profile-management.md

@@ -0,0 +1,323 @@
+# AWS Profile Management
+
+This document explains how `switch-profile` manages AWS profiles, SSO sessions, and credentials internally.
+
+## Overview
+
+All profile and credential logic lives in `src/aws/index.js`. This module directly reads and writes AWS configuration files using regex-based INI parsing - it does not shell out to `aws configure` for most operations.
+
+## File Locations
+
+| Path | Purpose | Managed By |
+|------|---------|------------|
+| `~/.aws/config` | Profile settings (region, output, SSO metadata) | `switch-profile` + `aws configure sso` |
+| `~/.aws/credentials` | Access keys, secrets, session tokens | `switch-profile` |
+| `~/.aws/sso/cache/` | SSO session tokens (JSON files) | AWS CLI |
+| `~/.aws/cli/cache/` | Temporary SSO credentials (JSON files) | AWS CLI |
+
+## Constants
+
+```javascript
+SSO_GET_CREDS_TIMEOUT = 300000  // 5 minutes to complete SSO login
+```
+
+## Functions Reference
+
+### Profile Listing
+
+#### `listProfiles()`
+
+Reads `~/.aws/config` and extracts all profile sections except `[default]`.
+
+**Returns:** `[errors, profiles[]]`
+
+Each profile object contains:
+
+```javascript
+{
+    name: 'sso-dev',                          // Profile name
+    friendlyName: 'sso-dev (SSO [role:Admin - account:123456])', // Display name
+    region: 'us-east-1',                      // AWS region
+    output: 'json',                           // Output format
+    sso_start_url: 'https://my.awsapps.com/start',  // null if not SSO
+    sso_region: 'us-east-1',                  // null if not SSO
+    sso_account_id: '123456789012',           // null if not SSO
+    sso_role_name: 'Admin'                    // null if not SSO
+}
+```
+
+**Parsing logic:**
+1. Matches all `[...]` sections in the config file.
+2. For each section, extracts the content between it and the next `[` bracket.
+3. Splits content by newline and extracts key-value pairs using `getParam()`.
+4. Strips `[profile ...]` prefix to get the profile name.
+5. For SSO profiles, uses `sso_region` as the effective region.
+6. Builds a `friendlyName` that includes role and account info for SSO profiles.
+
+#### `getDefaultProfile()`
+
+Reads the `[default]` section from `~/.aws/credentials`.
+
+**Returns:** `[errors, profile]`
+
+```javascript
+{
+    aws_access_key_id: 'AKIA...',
+    aws_secret_access_key: '...',
+    aws_session_token: '...',    // null for standard profiles
+    expiry_date: '2021-07-17...', // null for standard profiles
+    profile: 'sso-dev'           // Which profile these creds belong to
+}
+```
+
+The `profile` and `expiry_date` fields are custom additions by `switch-profile` - they are not standard AWS CLI fields. They are written into the credentials file so the tool can track which profile is currently active and when it expires.
+
+### Credential Retrieval
+
+#### `getCredentials(profile, ssoUrl)`
+
+The main credential retrieval function. Behaves differently for SSO vs. standard profiles.
+
+**For SSO profiles** (when `ssoUrl` is provided):
+
+1. Calls `refreshSsoSession()` to ensure a valid SSO session exists.
+2. Calls `getSsoCredentials()` to get temporary AWS credentials via the CLI cache.
+3. If credentials fail with "session associated with this profile has expired", forces a session refresh and retries.
+4. If `getSsoCredentials()` returns `null` (cache-based lookup failed), falls back to `aws configure export-credentials --profile <name> --format process` which directly outputs credentials as JSON.
+5. If both approaches fail, throws an error.
+
+**For standard profiles** (when `ssoUrl` is null):
+
+1. Reads `~/.aws/credentials`.
+2. Finds the `[profile-name]` section.
+3. Extracts `aws_access_key_id`, `aws_secret_access_key`, and `aws_session_token`.
+
+**Returns:** `[errors, { aws_access_key_id, aws_secret_access_key, aws_session_token, expiry_date }]`
+
+#### `getSsoCredentials(profile)`
+
+Gets SSO credentials by running `aws configure list --profile <profile>`, which triggers the AWS CLI to populate its credential cache.
+
+**Process:**
+1. Executes `aws configure list --profile <profile>`.
+2. Parses the output to extract the last 4 characters of the access key and secret key (the CLI masks them as `****XXXX`).
+3. Calls `getSsoCredsFromCacheFile()` to find the full credentials in the CLI cache.
+
+**Returns:** `[errors, creds]` or `[errors, null]` if credentials not found.
+
+#### `getSsoCredsFromCacheFile(access_key_end, secret_key_end)`
+
+Searches `~/.aws/cli/cache/` for a JSON file containing credentials that match the given key suffixes.
+
+**Matching criteria:**
+- `ProviderType` must be `"sso"`.
+- `Credentials.Expiration` must be at least 2 minutes in the future.
+- Last 4 characters of `AccessKeyId` must match `access_key_end`.
+- Last 4 characters of `SecretAccessKey` must match `secret_key_end`.
+
+**Returns:** `[errors, creds]` or `[errors, null]` if no match found.
+
+### SSO Session Management
+
+#### `getSsoSession(ssoUrl)`
+
+Finds a valid SSO session token in `~/.aws/sso/cache/`.
+
+**Process:**
+1. Extracts the host from `ssoUrl` (e.g., `my.awsapps.com`).
+2. Lists all `*.json` files in `~/.aws/sso/cache/`.
+3. For each file, checks if:
+   - `startUrl` host matches the SSO URL host.
+   - `expiresAt` is at least 2 minutes in the future.
+   - `accessToken` is present.
+
+**Returns:** `[errors, session]` or `[errors, null]` if no valid session found.
+
+#### `isSSOexpired(ssoSession)`
+
+Checks if an SSO session will expire within the next 2 minutes.
+
+**Returns:** `boolean`
+
+#### `refreshSsoSession(profile, ssoUrl, options)`
+
+Ensures a valid SSO session exists. If not, triggers a new SSO login.
+
+**Process:**
+1. Check for existing valid session via `getSsoSession()`.
+2. If expired or `options.force` is true:
+   - Runs `aws sso login --profile <profile>` (opens browser).
+   - Polls `getSsoSession()` every 2 seconds.
+   - Waits up to 5 minutes (`SSO_GET_CREDS_TIMEOUT`) for the session to appear.
+3. Returns the session object, or throws a timeout error.
+
+### Profile Modification
+
+#### `updateDefaultProfile({ profile, region, expiry_date, aws_access_key_id, aws_secret_access_key, aws_session_token })`
+
+Updates the `[default]` section in both `~/.aws/credentials` and `~/.aws/config`.
+
+**In `~/.aws/credentials`:**
+```ini
+[default]
+aws_access_key_id = AKIA...
+aws_secret_access_key = ...
+aws_session_token = ...          # Only for SSO profiles
+expiry_date = 2021-07-17T...     # Only for SSO profiles
+profile = sso-dev                # Custom field: tracks active profile
+```
+
+**In `~/.aws/config`:**
+```ini
+[default]
+region = us-east-1
+output = json
+```
+
+**Approach:** Uses regex to find the existing `[default]` section and replaces it. If no `[default]` section exists, prepends it. All other profile sections are preserved unchanged.
+
+#### `createProfile({ name, aws_access_key_id, aws_secret_access_key, region })`
+
+Creates a standard (non-SSO) profile.
+
+**Writes to `~/.aws/config`:**
+```ini
+[profile my-profile]
+region = us-east-1
+output = json
+```
+
+**Writes to `~/.aws/credentials`:**
+```ini
+[my-profile]
+aws_access_key_id = AKIA...
+aws_secret_access_key = ...
+```
+
+If the config or credentials files don't exist, they are created with a default `[default]` section first.
+
+#### `createSsoProfile(name)`
+
+Creates an SSO profile by spawning the interactive `aws configure sso --profile <name>` command. This hands control to the AWS CLI, which walks the user through the SSO setup (URL, region, account, role).
+
+Uses `spawn` with `stdio: 'inherit'` so the user interacts directly with the AWS CLI process. Checks the exit code of the spawned process and throws an error if it is non-zero, indicating the SSO setup failed.
+
+#### `deleteProfiles(profiles)`
+
+Deletes one or more profiles from both `~/.aws/config` and `~/.aws/credentials`.
+
+**Rules:**
+- The `default` profile cannot be deleted.
+- Uses regex matching to find and remove the profile section and everything up to the next `[` bracket.
+
+#### `deleteProfileFromConfig(profile, fileContent)` / `deleteProfileFromCreds(profile, fileContent)`
+
+Internal helpers that remove a single profile section from file content using regex. The config version handles both `[profile name]` and `[name]` syntax. The creds version handles `[name]` syntax only.
+
+### AWS CLI Detection
+
+#### `awsCliV2Exists(noFailIfMissing)`
+
+Checks that AWS CLI v2+ is installed.
+
+**Process:**
+1. Runs `which aws` (or `where aws` on Windows) to check if the command exists.
+2. Runs `aws --version` and parses the major version number.
+3. Rejects if version is 1 or lower.
+
+**Parameters:**
+- `noFailIfMissing`: If `true`, returns `false` instead of throwing when AWS CLI is not found.
+
+### Utility
+
+#### `getParam(params, paramName)`
+
+Extracts a parameter value from an array of lines in `key = value` format.
+
+```javascript
+getParam(['  region = us-east-1', '  output = json'], 'region')
+// Returns: 'us-east-1'
+```
+
+#### `getCredsFile()` / `getConfigFile()`
+
+Reads the credentials or config file and returns its contents as a string. Returns an empty string if the file doesn't exist.
+
+## SSO Credential Flow Diagram
+
+```
+User selects an SSO profile
+            │
+            ▼
+    getCredentials(profile, ssoUrl)
+            │
+            ▼
+    refreshSsoSession(profile, ssoUrl)
+            │
+            ├── getSsoSession(ssoUrl)
+            │       │
+            │       ▼
+            │   Search ~/.aws/sso/cache/*.json
+            │   for matching, non-expired session
+            │       │
+            │       ├── Found valid session → continue
+            │       │
+            │       └── Not found or expired
+            │               │
+            │               ▼
+            │       aws sso login --profile <name>
+            │       (opens browser for SSO auth)
+            │               │
+            │               ▼
+            │       Poll ~/.aws/sso/cache/ every 2s
+            │       (up to 5 min timeout)
+            │
+            ▼
+    getSsoCredentials(profile)
+            │
+            ▼
+    aws configure list --profile <name>
+    (populates ~/.aws/cli/cache/)
+            │
+            ▼
+    getSsoCredsFromCacheFile(keyEnd, secretEnd)
+            │
+            ▼
+    Search ~/.aws/cli/cache/*.json
+    for matching credentials
+            │
+            ├── Found → return credentials
+            │
+            └── Not found (null)
+                    │
+                    ▼
+            Fallback: aws configure export-credentials
+                      --profile <name> --format process
+            (directly outputs credentials as JSON)
+                    │
+                    ├── Success → return credentials
+                    │
+                    └── Failure → throw error
+            │
+            ▼
+    Return { aws_access_key_id,
+             aws_secret_access_key,
+             aws_session_token,
+             expiry_date }
+```
+
+## Expiry Handling
+
+The tool uses a 2-minute buffer for expiry checks throughout. A session or credential is considered expired if it expires within the next 2 minutes:
+
+```javascript
+const credStillValid = (Date.now() - 2*60*1000) < new Date(expiresAt).getTime()
+```
+
+This prevents credentials from expiring between the time they're fetched and the time they're used.
+
+## Profile Name Conventions
+
+- In `~/.aws/config`: Non-default profiles use `[profile name]` syntax. The default uses `[default]`.
+- In `~/.aws/credentials`: All profiles use `[name]` syntax (no `profile` prefix).
+- Profile names must be: lowercase alphanumeric characters, dashes, and underscores. Minimum 2 characters.

package/docs/cli-interface.md

@@ -0,0 +1,267 @@
+# 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:** Generic "not installed" message
+
+### 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:
+
+```
+AWS profile sso-dev successfully set up as default.   # Green
+```
+
+### 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.
+
+```
+AWS profile sso-dev successfully refreshed.    # Green
+```
+
+## 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 |
+
+## 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
+```