three-blocks-login 0.1.4 → 0.1.6

package/README.md

@@ -0,0 +1,248 @@
+# three-blocks-login
+
+Minimal, dependency-free CLI for authenticating to Three Blocks private npm registry (AWS CodeArtifact).
+
+## Quick Start
+
+```bash
+# Interactive login (writes to .npmrc in current directory)
+npx -y three-blocks-login@latest
+
+# Using pnpm (recommended - no warnings)
+pnpm dlx three-blocks-login@latest@latest
+```
+
+## Authentication Modes
+
+The CLI supports three modes for storing authentication:
+
+### 1. Project Mode (Recommended for CI/Vercel)
+
+Writes `.npmrc` to the current directory. Best for project-specific authentication.
+
+```bash
+npx -y three-blocks-login@latest --mode project --scope @three-blocks --channel stable
+```
+
+**Use this in package.json preinstall scripts:**
+
+```json
+{
+  "scripts": {
+    "preinstall": "npx -y three-blocks-login@latest"
+  }
+}
+```
+
+**Note:** Flags are optional - the CLI auto-detects `--mode project` in CI environments, defaults to `--scope @three-blocks`, and `--channel stable`.
+
+### 2. Env Mode (Temporary)
+
+Writes to a temporary `.npmrc` file and exports `NPM_CONFIG_USERCONFIG`. Useful for shell sessions.
+
+```bash
+eval "$(npx -y three-blocks-login@latest --mode env --print-shell)"
+```
+
+### 3. User Mode (Global)
+
+Updates your user's npm config (`~/.npmrc`). Affects all projects.
+
+```bash
+npx -y three-blocks-login@latest --mode user
+```
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--mode <env\|project\|user>` | Authentication storage mode | Auto-detected |
+| `--scope <scope>` | npm scope to authenticate | `@three-blocks` |
+| `--channel <stable\|alpha\|beta>` | Release channel | `stable` or `THREE_BLOCKS_CHANNEL` env |
+| `--license <key>` | License key (or use `THREE_BLOCKS_SECRET_KEY` env) | From env or prompt |
+| `--endpoint <url>` | Custom broker endpoint | `https://www.threejs-blocks.com/api/npm/token` |
+| `--quiet` / `-q` | Suppress non-error output | `false` |
+| `--verbose` / `-v` | Enable verbose logging | `false` |
+| `--debug` | Enable debug logging | `false` |
+| `--non-interactive` | Fail instead of prompting | `false` or `CI=1` |
+| `--print-shell` | Print shell export commands (env mode) | `false` or `THREE_BLOCKS_LOGIN_PRINT_SHELL=1` |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `THREE_BLOCKS_SECRET_KEY` | License key (format: `tb_...`) |
+| `THREE_BLOCKS_CHANNEL` | Release channel (`stable`, `alpha`, `beta`) |
+| `THREE_BLOCKS_BROKER_URL` | Custom broker endpoint URL |
+| `THREE_BLOCKS_DEBUG` | Enable debug logging (`1`, `true`, `yes`) |
+| `THREE_BLOCKS_USER_NAME` | Display name for welcome message |
+| `THREE_BLOCKS_LOGIN_PRINT_SHELL` | Print shell exports in env mode (`1`) |
+| `CI` | Enable non-interactive mode (`1`) |
+
+## CI/CD & Vercel Setup
+
+### Quick Setup (3 steps)
+
+1. **Commit a base `.npmrc`** to your repository (safe - no secrets):
+   ```
+   @three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/
+   ```
+
+2. **Add preinstall script** to package.json:
+   ```json
+   {
+     "scripts": {
+       "preinstall": "npx -y three-blocks-login@latest"
+     }
+   }
+   ```
+
+3. **Set environment variable** in Vercel/CI:
+   - **Name**: `THREE_BLOCKS_SECRET_KEY`
+   - **Value**: Your license key (starts with `tb_...`)
+
+### How It Works
+
+- Committed `.npmrc` tells pnpm **WHERE** to find packages
+- Preinstall script adds the **AUTH TOKEN** dynamically
+- This solves pnpm's resolution timing issue (it needs to know the registry before running preinstall)
+
+### Vercel Environment Variables
+
+1. Go to your Vercel project settings
+2. Navigate to: Settings → Environment Variables
+3. Add `THREE_BLOCKS_SECRET_KEY` environment variable
+4. Set the value to your license key (starts with `tb_...`)
+5. Make sure it's available in all environments (Production, Preview, Development)
+
+### GitHub Actions
+
+```yaml
+- name: Authenticate to Three Blocks
+  run: npx -y three-blocks-login@latest
+  env:
+    THREE_BLOCKS_SECRET_KEY: ${{ secrets.THREE_BLOCKS_SECRET_KEY }}
+```
+
+**Or better yet**, just rely on the preinstall script - GitHub Actions will run it automatically during `npm install` or `pnpm install`.
+
+## Troubleshooting
+
+### 401 Unauthorized on Vercel
+
+**Problem:** Getting `ERR_PNPM_FETCH_401` or npm 401 errors on Vercel.
+
+**Root Cause:** pnpm resolves package locations BEFORE running preinstall scripts.
+
+**Solution (3 steps):**
+
+1. **Commit a base `.npmrc`** with just the registry URL (no auth token):
+   ```
+   @three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/
+   ```
+
+2. **Add preinstall script**:
+   ```json
+   {
+     "scripts": {
+       "preinstall": "npx -y three-blocks-login@latest"
+     }
+   }
+   ```
+
+3. **Verify `THREE_BLOCKS_SECRET_KEY`** is set in Vercel environment variables
+
+**Why this works:**
+- Committed `.npmrc` tells pnpm WHERE to look for packages
+- Preinstall script adds the auth token dynamically
+- pnpm can now resolve packages AND authenticate when downloading
+
+### License Key Format
+
+License keys must:
+- Start with `tb_` prefix
+- Contain at least 10 characters after the prefix
+- Only contain characters: `A-Z`, `a-z`, `0-9`, `_`, `-`
+
+Example: `tb_AbC123XyZ456...`
+
+### Token Expiry
+
+Tokens are short-lived (typically 12 hours). If you see 401 errors:
+
+1. Check that `THREE_BLOCKS_SECRET_KEY` is set correctly
+2. Run the preinstall script manually to test: `npm run preinstall` or `pnpm preinstall`
+3. Verify the broker endpoint is accessible: `curl -I https://www.threejs-blocks.com/api/npm/token`
+
+### npm Config Warnings
+
+If you see warnings like `npm WARN invalid config unknown="..."`:
+
+- Use `pnpm dlx` instead of `npx`
+- Or ignore the warnings (they're harmless)
+
+## Security
+
+- License keys are validated locally before being sent to the broker
+- Tokens are masked in CLI output (`••••{last4}`)
+- `.npmrc` files are created with `0o600` permissions (read/write for owner only)
+- Sensitive environment variables are scrubbed before running npm commands
+
+### What's Safe to Commit?
+
+✅ **SAFE** - Base `.npmrc` with registry URL only:
+```
+@three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/
+```
+
+❌ **NEVER COMMIT** - Lines containing auth tokens:
+```
+//three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/:_authToken=eyJ2...
+```
+
+❌ **NEVER COMMIT** - `.env.local` with license keys
+
+Add to your `.gitignore`:
+
+```
+.env.local
+```
+
+**Note:** You can now commit `.npmrc` safely - the preinstall script merges auth tokens without overwriting your base configuration.
+
+## How It Works
+
+1. **License Key Validation**: The CLI validates your license key format locally
+2. **Broker Request**: Sends your license key to the broker endpoint via Bearer auth
+3. **Token Exchange**: The broker returns a short-lived npm token and registry URL
+4. **npm Configuration**: Writes authentication to `.npmrc` in the selected mode
+
+```
+License Key → Broker Service → Short-lived NPM Token → CodeArtifact Access
+```
+
+## License Tiers
+
+The CLI supports multiple license tiers:
+
+- **Indie/Core**: Access to `@three-blocks/core` package
+- **Pro**: Access to all `@three-blocks/*` packages including starter templates
+
+Your tier is determined by your license key and displayed in the CLI output.
+
+## Support
+
+For issues or questions:
+- Check the troubleshooting guide above
+- Review your Vercel environment variables
+- Verify your license key format
+- Contact Three Blocks support with your license ID (not the full key)
+
+## Version
+
+Current version: 0.1.4
+
+For the latest version, always use `@latest`:
+```bash
+npx -y three-blocks-login@latest
+```

package/bin/login.js

@@ -355,7 +355,7 @@ if ( DEBUG ) logDebug( "Debug logging enabled." );
 
 const SCOPE = ( args.scope || "@three-blocks" ).replace( /^\s+|\s+$/g, "" );
 
-const MODE = ( args.mode || "env" ).toLowerCase(); // env | project | user
+const MODE = ( args.mode || getDefaultMode() ).toLowerCase(); // env | project | user
 const QUIET = !! args.quiet;
 const VERBOSE = !! args.verbose;
 let CHANNEL = String( args.channel || process.env.THREE_BLOCKS_CHANNEL || "stable" ).toLowerCase();
@@ -608,10 +608,6 @@ const log = {
 				];
 				console.log( [ ...exportLines, '', ...summaryPrint ].join( '\n' ) );
 
-			} else {
-
-				log.info( `${plainBanner} temp npmrc ready. Use --print-shell to emit export commands.` );
-
 			}
 
 			return;
@@ -620,10 +616,62 @@ const log = {
 
 		if ( MODE === "project" ) {
 
-			// Write to local ./.npmrc (recommend users gitignore this)
+			// Write to local ./.npmrc - merge with existing content if present
 			const out = path.resolve( process.cwd(), ".npmrc" );
-			fs.writeFileSync( out, npmrcContent, { mode: 0o600 } );
-			log.ok( `${banner} wrote ${bold( out )} ${dim( `(${SCOPE} → ${u.href}, expires ${expiresAt ?? "unknown"})` )}` );
+			let existingContent = '';
+			try {
+
+				if ( fs.existsSync( out ) ) {
+
+					existingContent = fs.readFileSync( out, 'utf8' );
+
+				}
+
+			} catch {}
+
+			// Merge: remove any existing registry/auth lines for this scope, then append new ones
+			const lines = existingContent.split( /\r?\n/ );
+			const scopePattern = new RegExp( `^\\s*${normalizeScope( SCOPE ).replace( /[.*+?^${}()|[\]\\]/g, '\\$&' )}:registry\\s*=` );
+			const authPattern = new RegExp( `^\\s*\\/\\/${hostPath.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' )}:_authToken\\s*=` );
+			const filtered = lines.filter( ( line ) => ! scopePattern.test( line ) && ! authPattern.test( line ) );
+
+			// Preserve existing content but ensure it ends with newline
+			const base = filtered.join( os.EOL ).trim();
+			const merged = base ? `${base}${os.EOL}${os.EOL}${npmrcContent}` : npmrcContent;
+
+			fs.writeFileSync( out, merged, { mode: 0o600 } );
+
+			// Show authentication status (unless in quiet mode)
+
+			if ( ! QUIET ) {
+
+				const maskedLicense = maskLicense( LICENSE_CLEAN );
+
+				renderEnvHeader( {
+
+					scope: SCOPE,
+					registry: u.href,
+					expiresAt,
+					tmpFile: out,
+					licenseMasked: maskedLicense,
+					licenseId,
+					channel: CHANNEL,
+					status: authStatus,
+					plan,
+					teamName,
+					teamId,
+					repository,
+					domain,
+					region,
+					userDisplayName: USER_DISPLAY_NAME,
+				} );
+
+			} else {
+
+				log.ok( `${banner} wrote ${bold( out )} ${dim( `(${SCOPE} → ${u.href}, expires ${expiresAt ?? "unknown"})` )}` );
+
+			}
+
 			return;
 
 		}
@@ -714,6 +762,22 @@ function ensureTrailingSlash( url ) {
 
 }
 
+function getDefaultMode() {
+
+	try {
+
+		const lifecycle = String( process.env.npm_lifecycle_event || '' );
+		const userAgent = String( process.env.npm_config_user_agent || '' );
+		const isNpmScript = !! lifecycle || /npm|pnpm|yarn/i.test( userAgent );
+		const isCi = String( process.env.CI || '' ) === '1';
+		if ( isNpmScript || isCi ) return 'project';
+
+	} catch {}
+
+	return 'env';
+
+}
+
 function loadEnvFromDotfile( dir ) {
 
 	try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-blocks-login",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Fetch a short-lived token from the three-blocks broker and configure npm for the current context.",
   "type": "module",
   "bin": {