switch-profile 0.1.1 → 0.2.1

package/docs/configuration-files.md

@@ -0,0 +1,240 @@
+# 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

@@ -0,0 +1,168 @@
+# 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.

package/index.js

@@ -109,8 +109,38 @@ const createNewProfile = async (profiles, makeItDefault) => {
 		const [profileErrors] = await createProfile({ name, aws_access_key_id, aws_secret_access_key, region })
 		if (profileErrors)
 			return printAWSerrors([new Error('Fail to create profile'), ...profileErrors])
-	} else
-		await createSsoProfile(name)
+	} else {
+		console.log('')
+		console.log('┌─────────────────────────────────────────────────────────────────────┐'.cyan)
+		console.log('│                     SSO Profile Setup Guide                         │'.cyan)
+		console.log('├─────────────────────────────────────────────────────────────────────┤'.cyan)
+		console.log('│                                                                     │'.cyan)
+		console.log('│  You\'re about to run \'aws configure sso\'. Here\'s what to expect:    │'.cyan)
+		console.log('│                                                                     │'.cyan)
+		console.log('│  1. SSO session name'.bold + '                                                │'.cyan)
+		console.log('│     Provide a name (e.g., "my-company-sso").                        │'.cyan)
+		console.log('│     This enables token reuse across profiles and automatic refresh.  │'.cyan)
+		console.log('│     Skipping this uses the legacy format (no auto-refresh).          │'.cyan)
+		console.log('│                                                                     │'.cyan)
+		console.log('│  2. SSO start URL'.bold + '                                                   │'.cyan)
+		console.log('│     Your AWS SSO portal URL (e.g., https://my-co.awsapps.com/start) │'.cyan)
+		console.log('│     Ask your AWS administrator if you don\'t have it.                 │'.cyan)
+		console.log('│                                                                     │'.cyan)
+		console.log('│  3. SSO region'.bold + '                                                      │'.cyan)
+		console.log('│     The region where your SSO instance is configured.                │'.cyan)
+		console.log('│     WARNING: This is NOT your deployment region.                     │'.yellow)
+		console.log('│     Using the wrong region causes "invalid_grant" errors.            │'.yellow)
+		console.log('│                                                                     │'.cyan)
+		console.log('│  Docs: https://docs.aws.amazon.com/cli/latest/userguide/            │'.cyan)
+		console.log('│        cli-configure-sso.html                                       │'.cyan)
+		console.log('│                                                                     │'.cyan)
+		console.log('└─────────────────────────────────────────────────────────────────────┘'.cyan)
+		console.log('')
+
+		const [ssoErrors] = await createSsoProfile(name)
+		if (ssoErrors)
+			return printAWSerrors([new Error(`Fail to create SSO profile ${name}`), ...ssoErrors])
+	}
 
 	console.log(`New profile ${name.bold} successfully created 🚀`.green)
 
@@ -302,6 +332,9 @@ const switchCmd = async () => {
 const setProfileToDefault = async (profileName, profileList, successMsg) => {
 	const profile = profileList.find(p => p.friendlyName == profileName || p.name == profileName)
 
+	if (!profile)
+		return printAWSerrors([new Error(`Profile ${profileName.bold} was not found in ~/.aws/config. It may not have been created correctly. Try creating it again.`)], { noStack:true })
+
 	// Gets the AWS credentials for a specific profile. If that profile is an SSO profile, this function has a series of
 	// side-effects:
 	// 	- If the local SSO session stored under ~/.aws/sso/cache has expired, then it will redirect the user to the SSO portal and eventually refresh that ~/.aws/sso/cache.
@@ -310,6 +343,7 @@ const setProfileToDefault = async (profileName, profileList, successMsg) => {
 	if (credsErrors)
 		return printAWSerrors([new Error(`Fail to get credentials for profile ${profile.name}`), ...credsErrors])
 
+	// console.log(profile)
 	// console.log(creds)
 
 	const [errors] = await updateDefaultProfile({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switch-profile",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "main": "index.js",
   "bin": "index.js",
   "description": "NPX script that exposes terminal shortcut to easily switch between cloud configuration (aws, gcp).",
@@ -32,7 +32,7 @@
   "license": "BSD-3-Clause",
   "devDependencies": {
     "chai": "^4.1.2",
-    "eslint": "^6.8.0",
+    "eslint": "^10.0.0",
     "mocha": "^8.2.1",
     "standard-version": "^9.3.0"
   },

package/src/aws/index.js

@@ -7,10 +7,10 @@ const fileHelper = require('../fileHelper')
 const regions = require('./regions')
 
 const SSO_GET_CREDS_TIMEOUT = 5*60*1000 // 5 minutes to complete the SSO login
-const AWS_CONFIG_FILE = join(homedir(), '.aws/config')
-const AWS_CREDS_FILE = join(homedir(), '.aws/credentials')
-const AWS_SSO_FOLDER = join(homedir(), '.aws/sso/cache/')
-const AWS_CLI_FOLDER = join(homedir(), '.aws/cli/cache/')
+const AWS_CONFIG_FILE = join(homedir(), '.aws', 'config')
+const AWS_CREDS_FILE = join(homedir(), '.aws', 'credentials')
+const AWS_SSO_FOLDER = join(homedir(), '.aws', 'sso', 'cache')
+const AWS_CLI_FOLDER = join(homedir(), '.aws', 'cli', 'cache')
 const DEFAULT_CONFIG = 
 `[default]
 region = ap-southeast-1
@@ -189,14 +189,15 @@ const getSsoCredsFromCacheFile = (access_key_end, secret_key_end) => catchErrors
 
 	for (let i=0;i<files.length;i++) {
 		const _creds = await fileHelper.json.get(files[i])
+
 		// Creds must be SSO
 		if (!_creds || _creds.ProviderType != 'sso' || !_creds.Credentials)
 			continue
 
 		// Creds must still be valid for the next 2 minutes
 		if (_creds.Credentials.Expiration && (Date.now() - 2*60*1000) < new Date(_creds.Credentials.Expiration).getTime()) {
-			const credsMatch = _creds.Credentials.AccessKeyId||''.slice(-4) == access_key_end && 
-				_creds.Credentials.SecretAccessKey||''.slice(-4) == secret_key_end
+			const credsMatch = (_creds.Credentials.AccessKeyId||'').slice(-4) == access_key_end && 
+				(_creds.Credentials.SecretAccessKey||'').slice(-4) == secret_key_end
 
 			if (credsMatch)
 				return {
@@ -238,6 +239,7 @@ const getSsoCredentials = profile => catchErrors((async () => {
 			return null 
 
 		const [ssoCredsErrors, creds] = await getSsoCredsFromCacheFile(access_key_end, secret_key_end)
+
 		if (ssoCredsErrors)
 			throw wrapErrors(errMsg, ssoCredsErrors)
 		return creds
@@ -508,10 +510,12 @@ const createProfile = ({ name, aws_access_key_id, aws_secret_access_key, region
 
 const createSsoProfile = name => catchErrors((async () => {
 	await awsCliV2Exists()
-	await new Promise(next => {
+	const exitCode = await new Promise(next => {
 		const child = spawn('aws', ['configure', 'sso', '--profile', name],{ stdio: 'inherit' })
-		child.on('exit', next)
+		child.on('exit', code => next(code))
 	})
+	if (exitCode !== 0)
+		throw new Error(`'aws configure sso' exited with code ${exitCode}. The SSO profile may not have been created correctly.`)
 })())
 
 module.exports = {