three-blocks-login 0.1.11 → 0.1.12

package/README.md

@@ -16,7 +16,7 @@ npx -y three-blocks-login@latest@latest
 
 The CLI supports three modes for storing authentication:
 
-### 1. Project Mode (Recommended for CI/Vercel)
+### 1. Project Mode (Default)
 
 Writes `.npmrc` to the current directory. Best for project-specific authentication.
 
@@ -24,15 +24,7 @@ Writes `.npmrc` to the current directory. Best for project-specific authenticati
 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"
-  }
-}
-```
+**For CI/CD:** Run this command BEFORE `pnpm install`, not as a preinstall hook. See [CI/CD Setup](#cicd-setup) for platform-specific examples.
 
 **Note:** Flags are optional - the CLI auto-detects `--mode project` in CI environments, defaults to `--scope @three-blocks`, and `--channel stable`.
 
@@ -79,64 +71,77 @@ npx -y three-blocks-login@latest --mode user
 | `THREE_BLOCKS_LOGIN_PRINT_SHELL` | Print shell exports in env mode (`1`) |
 | `CI` | Enable non-interactive mode (`1`) |
 
-## CI/CD & Vercel Setup
+## CI/CD Setup
 
-### Quick Setup (3 steps)
+> ⚠️ **pnpm users:** The preinstall hook approach is unreliable with pnpm because pnpm resolves packages BEFORE running preinstall scripts. Use the **CI Install Override** approach below instead.
 
-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/
-   ```
+### Recommended: CI Install Override (All CIs)
 
-2. **Add preinstall script** to package.json:
-   ```json
-   {
-     "scripts": {
-       "preinstall": "npx -y three-blocks-login@latest"
-     }
-   }
-   ```
+Run the login command BEFORE `pnpm install`, not as a preinstall hook:
 
-3. **Set environment variable** in Vercel/CI:
-   - **Name**: `THREE_BLOCKS_SECRET_KEY`
-   - **Value**: Your license key (starts with `tb_...`)
+#### Vercel
+
+```json
+// vercel.json
+{
+  "installCommand": "npx -y three-blocks-login@latest && pnpm install"
+}
+```
 
-### How It Works
+Set `THREE_BLOCKS_SECRET_KEY` in Vercel → Project Settings → Environment Variables.
 
-- 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)
+#### AWS Amplify
 
-### Vercel Environment Variables
+```yaml
+# amplify.yml
+version: 1
+frontend:
+  phases:
+    preBuild:
+      commands:
+        - npx -y three-blocks-login@latest
+        - pnpm install
+    build:
+      commands:
+        - pnpm build
+```
 
-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)
+Set `THREE_BLOCKS_SECRET_KEY` in Amplify Console → App Settings → Environment Variables.
 
-### GitHub Actions
+#### GitHub Actions
 
 ```yaml
-- name: Authenticate to Three Blocks
+- name: Auth three-blocks
   run: npx -y three-blocks-login@latest
   env:
     THREE_BLOCKS_SECRET_KEY: ${{ secrets.THREE_BLOCKS_SECRET_KEY }}
+
+- name: Install dependencies
+  run: pnpm install
 ```
 
-**Or better yet**, just rely on the preinstall script - GitHub Actions will run it automatically during `npm install` or `pnpm install`.
+#### Netlify
 
-## Troubleshooting
+```toml
+# netlify.toml
+[build]
+  command = "npx -y three-blocks-login@latest && pnpm install && pnpm build"
+```
 
-### 401 Unauthorized on Vercel
+Set `THREE_BLOCKS_SECRET_KEY` in Netlify → Site Settings → Environment Variables.
 
-**Problem:** Getting `ERR_PNPM_FETCH_401` or npm 401 errors on Vercel.
+#### Generic CI
 
-**Root Cause:** pnpm resolves package locations BEFORE running preinstall scripts.
+Always run login before install:
+```bash
+npx -y three-blocks-login@latest && pnpm install
+```
+
+### Alternative: Preinstall Hook (npm only)
 
-**Solution (3 steps):**
+> ⚠️ This approach only works reliably with **npm**, not pnpm. For pnpm, use CI Install Override above.
 
-1. **Commit a base `.npmrc`** with just the registry URL (no auth token):
+1. **Commit a base `.npmrc`** (no auth token):
    ```
    @three-blocks:registry=https://three-blocks-196905988268.d.codeartifact.ap-northeast-1.amazonaws.com/npm/core/
    ```
@@ -150,12 +155,31 @@ npx -y three-blocks-login@latest --mode user
    }
    ```
 
-3. **Verify `THREE_BLOCKS_SECRET_KEY`** is set in Vercel environment variables
+3. **Set `THREE_BLOCKS_SECRET_KEY`** in CI environment variables.
+
+## Troubleshooting
+
+### 401 Unauthorized on Vercel/Amplify/CI
+
+**Problem:** Getting `ERR_PNPM_FETCH_401` or 401 errors in CI.
+
+**Root Cause:** pnpm resolves packages BEFORE running preinstall scripts. If you're using a preinstall hook with pnpm, it won't work reliably.
+
+**Solution:** Use CI Install Override instead of preinstall hooks.
+
+For Vercel, add to `vercel.json`:
+```json
+{
+  "installCommand": "npx -y three-blocks-login@latest && pnpm install"
+}
+```
+
+For other CIs, see the [CI/CD Setup](#cicd-setup) section above.
 
-**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
+**Also check:**
+- `THREE_BLOCKS_SECRET_KEY` is set in CI environment variables
+- `.npmrc` does NOT contain an `_authToken` line (tokens expire in 12h)
+- Remove any preinstall hook from `package.json` if using CI override
 
 ### License Key Format
 

package/bin/login.js

@@ -241,6 +241,32 @@ if ( SKIP_LOGIN ) {
 
 }
 
+// Detect pnpm + preinstall timing issue
+const isPnpmPreinstall = () => {
+
+	const lifecycle = String( process.env.npm_lifecycle_event || '' ).toLowerCase();
+	const userAgent = String( process.env.npm_config_user_agent || '' ).toLowerCase();
+	return lifecycle === 'preinstall' && userAgent.includes( 'pnpm' );
+
+};
+
+const warnPnpmPreinstall = () => {
+
+	if ( ! isPnpmPreinstall() || QUIET ) return;
+	console.error( '' );
+	console.error( cyan( '⚠' ) + ' ' + bold( 'pnpm preinstall timing warning' ) );
+	console.error( dim( '  pnpm resolves packages BEFORE running preinstall hooks.' ) );
+	console.error( dim( '  If you see 401 errors, use CI install command override instead:' ) );
+	console.error( '' );
+	console.error( dim( '  Vercel:  ' ) + cyan( '"installCommand": "npx -y three-blocks-login@latest && pnpm install"' ) );
+	console.error( dim( '  Amplify: ' ) + cyan( 'preBuild: npx -y three-blocks-login@latest && pnpm install' ) );
+	console.error( dim( '  Generic: ' ) + cyan( 'npx -y three-blocks-login@latest && pnpm install' ) );
+	console.error( '' );
+	console.error( dim( '  Docs: https://threejs-blocks.com/auth-guide' ) );
+	console.error( '' );
+
+};
+
 // Load .env from current working directory (no deps)
 loadEnvFromDotfile( process.cwd() );
 
@@ -722,6 +748,9 @@ const log = {
 
 ( async () => {
 
+	// Warn about pnpm preinstall timing issue early
+	warnPnpmPreinstall();
+
 	try {
 
 		let LICENSE = args.license || process.env.THREE_BLOCKS_SECRET_KEY;

package/package.json

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