three-blocks-login 0.1.3 → 0.1.4

package/bin/login.js

@@ -8,573 +8,980 @@ import path from "node:path";
 import readline from "node:readline";
 import { createRequire } from "node:module";
 
-const require = createRequire(import.meta.url);
-const pkg = require("../package.json");
-const CLI_VERSION = pkg?.version ? String(pkg.version) : "?.?.?";
+const require = createRequire( import.meta.url );
+const pkg = require( "../package.json" );
+const CLI_VERSION = pkg?.version ? String( pkg.version ) : "?.?.?";
 
 // Simple ANSI color helpers (no deps)
-const ESC = (n) => `\u001b[${n}m`;
-const reset = ESC(0);
-const bold = (s) => ESC(1) + s + reset;
-const dim = (s) => ESC(2) + s + reset;
-const red = (s) => ESC(31) + s + reset;
-const green = (s) => ESC(32) + s + reset;
-const yellow = (s) => ESC(33) + s + reset;
-const cyan = (s) => ESC(36) + s + reset;
+const ESC = ( n ) => `\u001b[${n}m`;
+const reset = ESC( 0 );
+const bold = ( s ) => ESC( 1 ) + s + reset;
+const dim = ( s ) => ESC( 2 ) + s + reset;
+const red = ( s ) => ESC( 31 ) + s + reset;
+const green = ( s ) => ESC( 32 ) + s + reset;
+const yellow = ( s ) => ESC( 33 ) + s + reset;
+const cyan = ( s ) => ESC( 36 ) + s + reset;
 const plainBanner = `[three-blocks-login@${pkg.version}]`;
-const banner = cyan(plainBanner);
+const banner = cyan( plainBanner );
 
-const quoteShell = (value) => JSON.stringify(String(value ?? ''));
+const quoteShell = ( value ) => JSON.stringify( String( value ?? '' ) );
+
+const BLOCKED_NPM_ENV_KEYS = new Set(
+	[
+		"npm_config__three_blocks_registry",
+		"npm_config_verify_deps_before_run",
+		"npm_config_global_bin_dir",
+		"npm_config__jsr_registry",
+		"npm_config_node_linker",
+	].map( ( key ) => key.replace( /-/g, "_" ).toLowerCase() )
+);
+
+const scrubNpmEnv = ( env = process.env ) => {
+
+	let removed = 0;
+	for ( const key of Object.keys( env ) ) {
+
+		const normalized = key.replace( /-/g, "_" ).toLowerCase();
+		if ( BLOCKED_NPM_ENV_KEYS.has( normalized ) ) {
+
+			delete env[ key ];
+			removed ++;
+
+		}
+
+	}
+
+	return removed;
+
+};
+
+scrubNpmEnv();
+
+let DEBUG = /^1|true|yes$/i.test( String( process.env.THREE_BLOCKS_DEBUG || "" ).trim() );
+
+const logDebug = ( msg ) => {
+
+	if ( DEBUG ) console.error( dim( `[debug] ${msg}` ) );
+
+};
+
+class CliError extends Error {
+
+	constructor( message, {
+		exitCode = 1,
+		command = "",
+		args = [],
+		stdout = "",
+		stderr = "",
+		suggestion = "",
+		cause = undefined,
+	} = {} ) {
+
+		super( message );
+		this.name = "CliError";
+		this.exitCode = exitCode;
+		this.command = command;
+		this.args = args;
+		this.stdout = stdout;
+		this.stderr = stderr;
+		this.suggestion = suggestion;
+		if ( cause ) this.cause = cause;
+
+	}
+
+}
+
+const quoteArg = ( value ) => {
+
+	const str = String( value ?? "" );
+	if ( /^[A-Za-z0-9._-]+$/.test( str ) ) return str;
+	return `'${str.replace( /'/g, `'\\''` )}'`;
+
+};
+
+const formatCommand = ( cmd, args = [] ) => [ cmd, ...args ].map( quoteArg ).join( " " );
 
 const HEADER_WIDTH = 96;
 const LEFT_WIDTH = 60;
 const RIGHT_WIDTH = HEADER_WIDTH - LEFT_WIDTH - 3;
 
-const repeatChar = (ch, len) => ch.repeat(Math.max(0, len));
-const stripAnsi = (value) => String(value ?? '').replace(/\u001b\[[0-9;]*m/g, '');
-const ellipsize = (value, width) => {
-  const str = String(value ?? '');
-  const plain = stripAnsi(str);
-  if (plain.length <= width) return str;
-  if (width <= 1) return plain.slice(0, width);
-  const truncated = plain.slice(0, width - 1) + '…';
-  return plain === str ? truncated : truncated;
+const repeatChar = ( ch, len ) => ch.repeat( Math.max( 0, len ) );
+const stripAnsi = ( value ) => String( value ?? '' ).replace( /\u001b\[[0-9;]*m/g, '' );
+const ellipsize = ( value, width ) => {
+
+	const str = String( value ?? '' );
+	const plain = stripAnsi( str );
+	if ( plain.length <= width ) return str;
+	if ( width <= 1 ) return plain.slice( 0, width );
+	const truncated = plain.slice( 0, width - 1 ) + '…';
+	return plain === str ? truncated : truncated;
+
 };
-const visibleLength = (value) => stripAnsi(String(value ?? '')).length;
-const padText = (value, width, align = 'left') => {
-  const text = ellipsize(value, width);
-  const current = visibleLength(text);
-  const remaining = width - current;
-  if (remaining <= 0) return text;
-  if (align === 'center') {
-    const left = Math.floor(remaining / 2);
-    const right = remaining - left;
-    return `${' '.repeat(left)}${text}${' '.repeat(right)}`;
-  }
-  if (align === 'right') {
-    return `${' '.repeat(remaining)}${text}`;
-  }
-  return `${text}${' '.repeat(remaining)}`;
+
+const visibleLength = ( value ) => stripAnsi( String( value ?? '' ) ).length;
+const padText = ( value, width, align = 'left' ) => {
+
+	const text = ellipsize( value, width );
+	const current = visibleLength( text );
+	const remaining = width - current;
+	if ( remaining <= 0 ) return text;
+	if ( align === 'center' ) {
+
+		const left = Math.floor( remaining / 2 );
+		const right = remaining - left;
+		return `${' '.repeat( left )}${text}${' '.repeat( right )}`;
+
+	}
+
+	if ( align === 'right' ) {
+
+		return `${' '.repeat( remaining )}${text}`;
+
+	}
+
+	return `${text}${' '.repeat( remaining )}`;
+
 };
-const makeHeaderRow = (left, right = '', leftAlign = 'left', rightAlign = 'left') =>
-  `│${padText(left, LEFT_WIDTH, leftAlign)}│${padText(right, RIGHT_WIDTH, rightAlign)}│`;
-
-const HEADER_COLOR = ESC(33);
-const CONTENT_COLOR = ESC(90); // bright black (grey)
-const reapplyColor = (value, color) => {
-  const str = String(value ?? '');
-  return `${color}${str.split(reset).join(`${reset}${color}`)}${reset}`;
+
+const makeHeaderRow = ( left, right = '', leftAlign = 'left', rightAlign = 'left' ) =>
+	`│${padText( left, LEFT_WIDTH, leftAlign )}│${padText( right, RIGHT_WIDTH, rightAlign )}│`;
+
+const HEADER_COLOR = ESC( 33 );
+const CONTENT_COLOR = ESC( 90 ); // bright black (grey)
+const reapplyColor = ( value, color ) => {
+
+	const str = String( value ?? '' );
+	return `${color}${str.split( reset ).join( `${reset}${color}` )}${reset}`;
+
 };
 
-const applyHeaderColor = (row, { keepContentYellow = false, tintContent = true } = {}) => {
-  if (keepContentYellow) return reapplyColor(row, HEADER_COLOR);
-  if (!row.startsWith('│') || !row.endsWith('│')) return reapplyColor(row, HEADER_COLOR);
-  const match = row.match(/^│(.*)│(.*)│$/);
-  if (!match) return reapplyColor(row, HEADER_COLOR);
-  const [, leftContent, rightContent] = match;
-  const leftSegment = tintContent ? reapplyColor(leftContent, CONTENT_COLOR) : leftContent;
-  const rightSegment = tintContent ? reapplyColor(rightContent, CONTENT_COLOR) : rightContent;
-  return `${HEADER_COLOR}│${reset}${leftSegment}${HEADER_COLOR}│${reset}${rightSegment}${HEADER_COLOR}│${reset}`;
+const applyHeaderColor = ( row, { keepContentYellow = false, tintContent = true } = {} ) => {
+
+	if ( keepContentYellow ) return reapplyColor( row, HEADER_COLOR );
+	if ( ! row.startsWith( '│' ) || ! row.endsWith( '│' ) ) return reapplyColor( row, HEADER_COLOR );
+	const match = row.match( /^│(.*)│(.*)│$/ );
+	if ( ! match ) return reapplyColor( row, HEADER_COLOR );
+	const [ , leftContent, rightContent ] = match;
+	const leftSegment = tintContent ? reapplyColor( leftContent, CONTENT_COLOR ) : leftContent;
+	const rightSegment = tintContent ? reapplyColor( rightContent, CONTENT_COLOR ) : rightContent;
+	return `${HEADER_COLOR}│${reset}${leftSegment}${HEADER_COLOR}│${reset}${rightSegment}${HEADER_COLOR}│${reset}`;
+
 };
 
-const formatRegistryShort = (value) => {
-  if (!value) return '';
-  try {
-    const u = new URL(value);
-    const pathname = (u.pathname || '').replace(/\/$/, '');
-    return `${u.host}${pathname}`;
-  } catch {
-    return String(value);
-  }
+const formatRegistryShort = ( value ) => {
+
+	if ( ! value ) return '';
+	try {
+
+		const u = new URL( value );
+		const pathname = ( u.pathname || '' ).replace( /\/$/, '' );
+		return `${u.host}${pathname}`;
+
+	} catch {
+
+		return String( value );
+
+	}
+
 };
 
-const maskLicense = (s) => {
-  if (!s) return '••••';
-  const v = String(s);
-  if (v.length <= 8) return '••••';
-  return `${v.slice(0, 4)}••••${v.slice(-4)}`;
+const maskLicense = ( s ) => {
+
+	if ( ! s ) return '••••';
+	const v = String( s );
+	if ( v.length <= 8 ) return '••••';
+	return `${v.slice( 0, 4 )}••••${v.slice( - 4 )}`;
+
 };
 
-const capitalize = (value) => {
-  const str = String(value || '').trim();
-  if (!str) return '';
-  return str[0].toUpperCase() + str.slice(1);
+const capitalize = ( value ) => {
+
+	const str = String( value || '' ).trim();
+	if ( ! str ) return '';
+	return str[ 0 ].toUpperCase() + str.slice( 1 );
+
 };
 
-const formatPlanLabel = (value) => {
-  const str = String(value || '').trim();
-  if (!str) return '';
-  return str
-    .split(/\s+/)
-    .map((part) => (part ? capitalize(part.toLowerCase()) : ''))
-    .join(' ')
-    .trim();
+const formatPlanLabel = ( value ) => {
+
+	const str = String( value || '' ).trim();
+	if ( ! str ) return '';
+	return str
+		.split( /\s+/ )
+		.map( ( part ) => ( part ? capitalize( part.toLowerCase() ) : '' ) )
+		.join( ' ' )
+		.trim();
+
 };
 
-const normalizePlan = (plan) => {
-  const label = formatPlanLabel(plan);
-  if (!label) return 'Developer Plan';
-  return label.toLowerCase().includes('plan') ? label : `${label} Plan`;
+const normalizePlan = ( plan ) => {
+
+	const label = formatPlanLabel( plan );
+	if ( ! label ) return 'Developer Plan';
+	return label.toLowerCase().includes( 'plan' ) ? label : `${label} Plan`;
+
 };
 
-const formatFirstName = (value) => {
-  const name = String(value || '').trim();
-  if (!name) return '';
-  const first = name.split(/\s+/)[0];
-  return capitalize(first.toLowerCase());
+const formatFirstName = ( value ) => {
+
+	const name = String( value || '' ).trim();
+	if ( ! name ) return '';
+	const first = name.split( /\s+/ )[ 0 ];
+	return capitalize( first.toLowerCase() );
+
 };
 
 const getUserDisplayName = () => {
-  const candidate =
+
+	const candidate =
     process.env.THREE_BLOCKS_USER_NAME ||
     process.env.GIT_AUTHOR_NAME ||
     process.env.USER ||
     process.env.LOGNAME;
-  if (candidate) return formatFirstName(candidate);
-  try {
-    return formatFirstName(os.userInfo().username);
-  } catch {
-    return '';
-  }
+	if ( candidate ) return formatFirstName( candidate );
+	try {
+
+		return formatFirstName( os.userInfo().username );
+
+	} catch {
+
+		return '';
+
+	}
+
 };
 
-const formatExpiryLabel = (iso) => {
-  if (!iso) return 'Expires: —';
-  const dt = new Date(iso);
-  if (Number.isNaN(dt.getTime())) return `Expires: ${iso}`;
-  return `Expires: ${dt.toISOString().replace('T', ' ').replace('Z', 'Z')}`;
+const formatExpiryLabel = ( iso ) => {
+
+	if ( ! iso ) return 'Expires: —';
+	const dt = new Date( iso );
+	if ( Number.isNaN( dt.getTime() ) ) return `Expires: ${iso}`;
+	return `Expires: ${dt.toISOString().replace( 'T', ' ' ).replace( 'Z', 'Z' )}`;
+
 };
 
 const USER_DISPLAY_NAME = getUserDisplayName();
 
-const renderEnvHeader = ({
-  scope,
-  registry,
-  expiresAt,
-  tmpFile,
-  licenseMasked,
-  licenseId,
-  channel,
-  status,
-  plan,
-  teamName,
-  teamId,
-  repository,
-  domain,
-  region,
-  userDisplayName,
-}) => {
-  const title = `─── Three Blocks Login v${CLI_VERSION} `;
-  const separatorRow = makeHeaderRow(repeatChar('─', LEFT_WIDTH), repeatChar('─', RIGHT_WIDTH));
-  const channelDisplay = String(channel || '').toUpperCase() || 'STABLE';
-  const registryShort = formatRegistryShort(registry);
-
-  const displayName = userDisplayName || USER_DISPLAY_NAME;
-  const welcomeLine = displayName ? `Welcome back ${displayName}!` : 'Welcome back!';
-  const scopeLine = `Scope: ${scope}`;
-
-  const planLabel = normalizePlan(plan);
-  const teamLabel = teamName || teamId ? ` · Team: ${teamName || teamId}` : '';
-  const subscriptionLine = `Plan: ${planLabel}${teamLabel}`;
-  const channelLine = `Channel: ${channelDisplay}${region ? ` · Region: ${region}` : ''}`;
-
-  const repositoryBase = repository ? `Repository: ${repository}` : 'Repository: —';
-  const repositoryLine = registryShort ? `${repositoryBase} → ${registryShort}` : repositoryBase;
-  const registryLine = `Registry: ${registryShort || (registry || '—')}`;
-
-  let domainValue = domain || '';
-  if (!domainValue && registry) {
-    try {
-      domainValue = new URL(registry).host;
-    } catch {}
-  }
-  const domainLineText = `Domain: ${domainValue || '—'}`;
-  const regionLineText = `Region: ${region || '—'}`;
-
-  const licenseLine = `License: ${licenseMasked}${licenseId ? ` · ${licenseId}` : ''}`;
-  const expiresLine = formatExpiryLabel(expiresAt);
-
-  const ascii = [
-    'THREE.JS',
-    ' ______     __         ______     ______     __  __     ______   ',
-    '/\\  == \\   /\\ \\       /\\  __ \\   /\\  ___\\   /\\ \\/ /    /\\  ___\\  ',
-    '\\ \\  __<   \\ \\ \\____  \\ \\ \\/\\ \\  \\ \\ \\____  \\ \\  _"-.  \\ \\___  \\ ',
-    ' \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_\\ \\_\\  \\/\\_____\\',
-    '  \\/_____\/   \\/_____/   \\/_____/   \\/_____/   \\/_/ \/_/   \\/_____/'
-  ];
-  const statusMessage = status?.message || (status?.ok ? 'access granted' : status ? 'no active access' : 'pending');
-  const statusText = status?.ok
-    ? green(bold(`Authenticated — ${statusMessage}`))
-    : status
-      ? red(bold(`Not authenticated — ${statusMessage}`))
-      : dim(bold(`Status: ${statusMessage}`));
-
-  const lines = [
-    applyHeaderColor(`╭${title}${repeatChar('─', HEADER_WIDTH - 2 - title.length)}╮`, { keepContentYellow: true }),
-    ...ascii.map((row) => applyHeaderColor(`│${padText(row, LEFT_WIDTH + RIGHT_WIDTH + 1, 'center')}│`, { keepContentYellow: true })),
-    applyHeaderColor(separatorRow, { keepContentYellow: true }),
-    applyHeaderColor(makeHeaderRow(welcomeLine, scopeLine, 'center', 'center')),
-    applyHeaderColor(separatorRow, { keepContentYellow: true }),
-    applyHeaderColor(makeHeaderRow(subscriptionLine, channelLine)),
-    applyHeaderColor(makeHeaderRow(repositoryLine, registryLine)),
-    applyHeaderColor(makeHeaderRow(domainLineText, regionLineText, 'left', 'center')),
-    applyHeaderColor(makeHeaderRow(licenseLine, expiresLine)),
-    applyHeaderColor(separatorRow, { keepContentYellow: true }),
-    applyHeaderColor(makeHeaderRow(statusText, '', 'left', 'center'), { tintContent: false }),
-    applyHeaderColor(`╰${repeatChar('─', HEADER_WIDTH - 2)}╯`, { keepContentYellow: true }),
-  ];
-  for (const row of lines) console.log(row);
+const renderEnvHeader = ( {
+	scope,
+	registry,
+	expiresAt,
+	tmpFile,
+	licenseMasked,
+	licenseId,
+	channel,
+	status,
+	plan,
+	teamName,
+	teamId,
+	repository,
+	domain,
+	region,
+	userDisplayName,
+} ) => {
+
+	const title = `─── Three Blocks Login v${CLI_VERSION} `;
+	const separatorRow = makeHeaderRow( repeatChar( '─', LEFT_WIDTH ), repeatChar( '─', RIGHT_WIDTH ) );
+	const channelDisplay = String( channel || '' ).toUpperCase() || 'STABLE';
+	const registryShort = formatRegistryShort( registry );
+
+	const displayName = userDisplayName || USER_DISPLAY_NAME;
+	const welcomeLine = displayName ? `Welcome back ${displayName}!` : 'Welcome back!';
+	const scopeLine = `Scope: ${scope}`;
+
+	const planLabel = normalizePlan( plan );
+	const teamLabel = teamName || teamId ? ` · Team: ${teamName || teamId}` : '';
+	const subscriptionLine = `Plan: ${planLabel}${teamLabel}`;
+	const channelLine = `Channel: ${channelDisplay}${region ? ` · Region: ${region}` : ''}`;
+
+	const repositoryBase = repository ? `Repository: ${repository}` : 'Repository: —';
+	const repositoryLine = registryShort ? `${repositoryBase} → ${registryShort}` : repositoryBase;
+	const registryLine = `Registry: ${registryShort || ( registry || '—' )}`;
+
+	let domainValue = domain || '';
+	if ( ! domainValue && registry ) {
+
+		try {
+
+			domainValue = new URL( registry ).host;
+
+		} catch {}
+
+	}
+
+	const domainLineText = `Domain: ${domainValue || '—'}`;
+	const regionLineText = `Region: ${region || '—'}`;
+
+	const licenseLine = `License: ${licenseMasked}${licenseId ? ` · ${licenseId}` : ''}`;
+	const expiresLine = formatExpiryLabel( expiresAt );
+
+	const ascii = [
+		'THREE.JS',
+		' ______     __         ______     ______     __  __     ______   ',
+		'/\\  == \\   /\\ \\       /\\  __ \\   /\\  ___\\   /\\ \\/ /    /\\  ___\\  ',
+		'\\ \\  __<   \\ \\ \\____  \\ \\ \\/\\ \\  \\ \\ \\____  \\ \\  _"-.  \\ \\___  \\ ',
+		' \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_\\ \\_\\  \\/\\_____\\',
+		'  \\/_____\/   \\/_____/   \\/_____/   \\/_____/   \\/_/ \/_/   \\/_____/'
+	];
+	const statusMessage = status?.message || ( status?.ok ? 'access granted' : status ? 'no active access' : 'pending' );
+	const statusText = status?.ok
+		? green( bold( `Authenticated — ${statusMessage}` ) )
+		: status
+			? red( bold( `Not authenticated — ${statusMessage}` ) )
+			: dim( bold( `Status: ${statusMessage}` ) );
+
+	const lines = [
+		applyHeaderColor( `╭${title}${repeatChar( '─', HEADER_WIDTH - 2 - title.length )}╮`, { keepContentYellow: true } ),
+		...ascii.map( ( row ) => applyHeaderColor( `│${padText( row, LEFT_WIDTH + RIGHT_WIDTH + 1, 'center' )}│`, { keepContentYellow: true } ) ),
+		applyHeaderColor( separatorRow, { keepContentYellow: true } ),
+		applyHeaderColor( makeHeaderRow( welcomeLine, scopeLine, 'center', 'center' ) ),
+		applyHeaderColor( separatorRow, { keepContentYellow: true } ),
+		applyHeaderColor( makeHeaderRow( subscriptionLine, channelLine ) ),
+		applyHeaderColor( makeHeaderRow( repositoryLine, registryLine ) ),
+		applyHeaderColor( makeHeaderRow( domainLineText, regionLineText, 'left', 'center' ) ),
+		applyHeaderColor( makeHeaderRow( licenseLine, expiresLine ) ),
+		applyHeaderColor( separatorRow, { keepContentYellow: true } ),
+		applyHeaderColor( makeHeaderRow( statusText, '', 'left', 'center' ), { tintContent: false } ),
+		applyHeaderColor( `╰${repeatChar( '─', HEADER_WIDTH - 2 )}╯`, { keepContentYellow: true } ),
+	];
+	for ( const row of lines ) console.log( row );
+
 };
 
-const args = parseArgs(process.argv.slice(2));
+const args = parseArgs( process.argv.slice( 2 ) );
 
-const SCOPE = (args.scope || "@three-blocks").replace(/^\s+|\s+$/g, "");
+DEBUG = DEBUG || !! args.debug || !! args.verbose;
+if ( DEBUG ) logDebug( "Debug logging enabled." );
 
-const MODE = (args.mode || "env").toLowerCase(); // env | project | user
-const QUIET = !!args.quiet;
-const VERBOSE = !!args.verbose;
-let CHANNEL = String(args.channel || process.env.THREE_BLOCKS_CHANNEL || "stable").toLowerCase();
-if (!['stable','alpha','beta'].includes(CHANNEL)) CHANNEL = 'stable';
-const PRINT_SHELL = !!(args['print-shell'] || args.printShell || process.env.THREE_BLOCKS_LOGIN_PRINT_SHELL === '1');
-const NON_INTERACTIVE = !!(args['non-interactive'] || args.nonInteractive || process.env.CI === '1');
+const SCOPE = ( args.scope || "@three-blocks" ).replace( /^\s+|\s+$/g, "" );
+
+const MODE = ( args.mode || "env" ).toLowerCase(); // env | project | user
+const QUIET = !! args.quiet;
+const VERBOSE = !! args.verbose;
+let CHANNEL = String( args.channel || process.env.THREE_BLOCKS_CHANNEL || "stable" ).toLowerCase();
+if ( ! [ 'stable', 'alpha', 'beta' ].includes( CHANNEL ) ) CHANNEL = 'stable';
+const PRINT_SHELL = !! ( args[ 'print-shell' ] || args.printShell || process.env.THREE_BLOCKS_LOGIN_PRINT_SHELL === '1' );
+const NON_INTERACTIVE = !! ( args[ 'non-interactive' ] || args.nonInteractive || process.env.CI === '1' );
 
 // Load .env from current working directory (no deps)
-loadEnvFromDotfile(process.cwd());
+loadEnvFromDotfile( process.cwd() );
 
 const BROKER_URL =
   args.endpoint ||
   process.env.THREE_BLOCKS_BROKER_URL ||
   "https://www.threejs-blocks.com/api/npm/token"; // your Astro broker endpoint
 
-  console.log(BROKER_URL)
-const promptHidden = async (label) => {
-  return await new Promise((resolve) => {
-    const stdin = process.stdin;
-    const stdout = process.stdout;
-    let value = '';
-    const cleanup = () => {
-      stdin.removeListener('data', onData);
-      if (stdin.isTTY) stdin.setRawMode(false);
-      stdin.pause();
-    };
-    const onData = (chunk) => {
-      const str = String(chunk);
-      for (const ch of str) {
-        if (ch === '\u0003') { cleanup(); process.exit(1); }
-        if (ch === '\r' || ch === '\n' || ch === '\u0004') {
-          stdout.write('\n');
-          cleanup();
-          return resolve(value.trim());
-        }
-        if (ch === '\b' || ch === '\u007f') {
-          if (value.length) {
-            value = value.slice(0, -1);
-            readline.moveCursor(stdout, -1, 0);
-            stdout.write(' ');
-            readline.moveCursor(stdout, -1, 0);
-          }
-          continue;
-        }
-        if (ch === '\u001b') continue;
-        value += ch;
-        stdout.write('•');
-      }
-    };
-    stdout.write(label);
-    stdin.setEncoding('utf8');
-    if (stdin.isTTY) stdin.setRawMode(true);
-    stdin.resume();
-    stdin.on('data', onData);
-  });
+console.log( BROKER_URL );
+const promptHidden = async ( label ) => {
+
+	return await new Promise( ( resolve ) => {
+
+		const stdin = process.stdin;
+		const stdout = process.stdout;
+		let value = '';
+		const cleanup = () => {
+
+			stdin.removeListener( 'data', onData );
+			if ( stdin.isTTY ) stdin.setRawMode( false );
+			stdin.pause();
+
+		};
+
+		const onData = ( chunk ) => {
+
+			const str = String( chunk );
+			for ( const ch of str ) {
+
+				if ( ch === '\u0003' ) {
+
+					cleanup(); process.exit( 1 );
+
+				}
+
+				if ( ch === '\r' || ch === '\n' || ch === '\u0004' ) {
+
+					stdout.write( '\n' );
+					cleanup();
+					return resolve( value.trim() );
+
+				}
+
+				if ( ch === '\b' || ch === '\u007f' ) {
+
+					if ( value.length ) {
+
+						value = value.slice( 0, - 1 );
+						readline.moveCursor( stdout, - 1, 0 );
+						stdout.write( ' ' );
+						readline.moveCursor( stdout, - 1, 0 );
+
+					}
+
+					continue;
+
+				}
+
+				if ( ch === '\u001b' ) continue;
+				value += ch;
+				stdout.write( '•' );
+
+			}
+
+		};
+
+		stdout.write( label );
+		stdin.setEncoding( 'utf8' );
+		if ( stdin.isTTY ) stdin.setRawMode( true );
+		stdin.resume();
+		stdin.on( 'data', onData );
+
+	} );
+
 };
 
 // Pretty logger (respects --quiet except for errors)
 const log = {
-  info: (msg) => { if (!QUIET) console.error(`${cyan("i")} ${msg}`); },
-  ok:   (msg) => { if (!QUIET) console.error(`${green("✔")} ${msg}`); },
-  warn: (msg) => { if (!QUIET) console.error(`${yellow("⚠")} ${msg}`); },
-  error:(msg) => { console.error(`${red("✖")} ${msg}`); }
+	info: ( msg ) => {
+
+		if ( ! QUIET ) console.error( `${cyan( "i" )} ${msg}` );
+
+	},
+	ok: ( msg ) => {
+
+		if ( ! QUIET ) console.error( `${green( "✔" )} ${msg}` );
+
+	},
+	warn: ( msg ) => {
+
+		if ( ! QUIET ) console.error( `${yellow( "⚠" )} ${msg}` );
+
+	},
+	error: ( msg ) => {
+
+		console.error( `${red( "✖" )} ${msg}` );
+
+	}
 };
 
-(async () => {
-  try {
-    let LICENSE = args.license || process.env.THREE_BLOCKS_SECRET_KEY;
-
-    if (!LICENSE || String(LICENSE).trim() === "") {
-      if (NON_INTERACTIVE) {
-        fail("Missing license key. Provide --license <key> or set THREE_BLOCKS_SECRET_KEY in your environment.");
-      }
-      console.log('');
-      log.info(bold(yellow('Three Blocks Login')) + ' ' + dim(`[mode: ${MODE}]`));
-      log.info(dim('Enter your license key to retrieve a scoped npm token.'));
-      log.info(dim('Tip: paste it here; input is hidden. Press Enter to submit.'));
-      LICENSE = await promptHidden(`${cyan('›')} License key ${dim('(tb_…)')}: `);
-      if (!LICENSE) fail('License key is required to continue.');
-    }
-
-    // Sanitize + validate license early to avoid header ByteString errors
-    const LICENSE_CLEAN = sanitizeLicense(LICENSE);
-    if (!LICENSE_CLEAN) {
-      fail(
-        "Missing license key. Provide --license <key> or set THREE_BLOCKS_SECRET_KEY in your .env file."
-      );
-    }
-    const invalidIdx = findFirstNonByteChar(LICENSE_CLEAN);
-    if (invalidIdx !== -1) {
-      if (VERBOSE) log.warn(`[debug] license contains non-ASCII/byte char at index ${invalidIdx}`);
-      fail("License appears malformed. Please copy your tb_… key exactly without extra characters.");
-    }
-    if (!looksLikeLicense(LICENSE_CLEAN)) {
-      if (VERBOSE) log.warn(`[debug] license failed format check: ${truncate(LICENSE_CLEAN, 16)}`);
-      fail("License appears malformed. Please copy your tb_… key exactly.");
-    }
-
-    const tokenData = await fetchToken(BROKER_URL, LICENSE_CLEAN, CHANNEL);
-    const {
-      registry,
-      token,
-      expiresAt,
-      status: rawStatus,
-      plan,
-      teamName,
-      teamId,
-      repository,
-      domain,
-      region,
-      licenseId,
-    } = tokenData;
-    const authStatus = rawStatus ?? { ok: true, message: 'access granted' };
-
-    if (!registry || !token) fail("Broker response missing registry/token.");
-
-    const u = new URL(ensureTrailingSlash(registry));
-    const hostPath = `${u.host}${u.pathname}`; // e.g. my-domain-.../npm/my-repo/
-
-    const npmrcContent = [
-      `${normalizeScope(SCOPE)}:registry=${u.href}`,
-      `//${hostPath}:_authToken=${token}`
-    ].join(os.EOL) + os.EOL;
-
-    if (MODE === "env") {
-      // Write to a temp .npmrc and export env so the *current shell* can reuse it
-      const tmpFile = path.join(
-        os.tmpdir(),
-        `three-blocks-${Date.now()}-${Math.random().toString(36).slice(2)}.npmrc`
-      );
-      fs.writeFileSync(tmpFile, npmrcContent, { mode: 0o600 });
-
-      // Print shell exports; caller should `eval "$(npx -y three-blocks-login --mode env)"`
-      const maskedLicense = maskLicense(LICENSE_CLEAN);
-      renderEnvHeader({
-        scope: SCOPE,
-        registry: u.href,
-        expiresAt,
-        tmpFile,
-        licenseMasked: maskedLicense,
-        licenseId,
-        channel: CHANNEL,
-        status: authStatus,
-        plan,
-        teamName,
-        teamId,
-        repository,
-        domain,
-        region,
-        userDisplayName: USER_DISPLAY_NAME,
-      });
-      if (PRINT_SHELL) {
-        const exportLines = [
-          `export NPM_CONFIG_USERCONFIG=${quoteShell(tmpFile)}`,
-          `export npm_config_userconfig=${quoteShell(tmpFile)}`,
-          `export THREE_BLOCKS_CHANNEL=${quoteShell(CHANNEL)}`,
-        ];
-        const summaryPrint = [
-          `cat <<'EOF'`,
-          `${plainBanner} scoped login ready (${authStatus.ok ? 'ok' : 'error'})`,
-          `  scope    : ${SCOPE}`,
-          `  registry : ${u.href}`,
-          `  expires  : ${expiresAt ?? 'unknown'}`,
-          `  license  : ${maskedLicense}`,
-          `  npmrc    : ${tmpFile}`,
-          `EOF`,
-        ];
-        console.log([...exportLines, '', ...summaryPrint].join('\n'));
-      } else {
-        log.info(`${plainBanner} temp npmrc ready. Use --print-shell to emit export commands.`);
-      }
-      return;
-    }
-
-    if (MODE === "project") {
-      // Write to local ./.npmrc (recommend users gitignore this)
-      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"})`)}`);
-      return;
-    }
-
-    if (MODE === "user") {
-      // Update user's npm config (requires npm on PATH)
-      await run("npm", ["config", "set", `${normalizeScope(SCOPE)}:registry`, u.href]);
-      await run("npm", [
-        "config",
-        "set",
-        `//${hostPath}:_authToken`,
-        token
-      ]);
-      log.ok(`${banner} updated user npm config ${dim(`(${SCOPE} → ${u.href}, expires ${expiresAt ?? "unknown"})`)}`);
-      return;
-    }
-
-    fail(`Unknown --mode "${MODE}". Use env | project | user.`);
-  } catch (e) {
-    const msg = e?.message || String(e);
-    if (VERBOSE) {
-      log.error(`[debug] ${msg}`);
-      return process.exit(1);
-    }
-    if (/ByteString/i.test(msg) || /character at index/i.test(msg)) {
-      return fail("License appears malformed. Please copy your tb_… key exactly and retry.");
-    }
-    return fail("Authentication failed. Please try again. Use --verbose for details.");
-  }
-})();
-
-function normalizeScope(scope) {
-  return scope.startsWith("@") ? scope : `@${scope}`;
+( async () => {
+
+	try {
+
+		let LICENSE = args.license || process.env.THREE_BLOCKS_SECRET_KEY;
+
+		if ( ! LICENSE || String( LICENSE ).trim() === "" ) {
+
+			if ( NON_INTERACTIVE ) {
+
+				fail(
+					"Missing license key. Provide --license <key> or set THREE_BLOCKS_SECRET_KEY in your environment.",
+					{ suggestion: "Pass --license tb_… or export THREE_BLOCKS_SECRET_KEY before running the CLI." }
+				);
+
+			}
+
+			console.log( '' );
+			log.info( bold( yellow( 'Three Blocks Login' ) ) + ' ' + dim( `[mode: ${MODE}]` ) );
+			log.info( dim( 'Enter your license key to retrieve a scoped npm token.' ) );
+			log.info( dim( 'Tip: paste it here; input is hidden. Press Enter to submit.' ) );
+			LICENSE = await promptHidden( `${cyan( '›' )} License key ${dim( '(tb_…)' )}: ` );
+			if ( ! LICENSE ) {
+
+				fail(
+					"License key is required to continue.",
+					{ suggestion: "Paste your tb_… key or rerun with --license." }
+				);
+
+			}
+
+		}
+
+		// Sanitize + validate license early to avoid header ByteString errors
+		const LICENSE_CLEAN = sanitizeLicense( LICENSE );
+		if ( ! LICENSE_CLEAN ) {
+
+			fail(
+				"Missing license key. Provide --license <key> or set THREE_BLOCKS_SECRET_KEY in your .env file.",
+				{ suggestion: "Set THREE_BLOCKS_SECRET_KEY=tb_… in your environment or pass --license tb_…" }
+			);
+
+		}
+
+		const invalidIdx = findFirstNonByteChar( LICENSE_CLEAN );
+		if ( invalidIdx !== - 1 ) {
+
+			if ( VERBOSE ) log.warn( `[debug] license contains non-ASCII/byte char at index ${invalidIdx}` );
+			fail(
+				"License appears malformed. Please copy your tb_… key exactly without extra characters.",
+				{ suggestion: "Remove spaces or smart quotes around the tb_… key and retry." }
+			);
+
+		}
+
+		if ( ! looksLikeLicense( LICENSE_CLEAN ) ) {
+
+			if ( VERBOSE ) log.warn( `[debug] license failed format check: ${truncate( LICENSE_CLEAN, 16 )}` );
+			fail(
+				"License appears malformed. Please copy your tb_… key exactly.",
+				{ suggestion: "Double-check the license string and avoid truncating it." }
+			);
+
+		}
+
+		const tokenData = await fetchToken( BROKER_URL, LICENSE_CLEAN, CHANNEL );
+		const {
+			registry,
+			token,
+			expiresAt,
+			status: rawStatus,
+			plan,
+			teamName,
+			teamId,
+			repository,
+			domain,
+			region,
+			licenseId,
+		} = tokenData;
+		const authStatus = rawStatus ?? { ok: true, message: 'access granted' };
+
+		if ( ! registry || ! token ) {
+
+			fail(
+				"Broker response missing registry/token.",
+				{ suggestion: "Retry the login or contact support; the broker response was incomplete." }
+			);
+
+		}
+
+		const u = new URL( ensureTrailingSlash( registry ) );
+		const hostPath = `${u.host}${u.pathname}`; // e.g. my-domain-.../npm/my-repo/
+
+		const npmrcContent = [
+			`${normalizeScope( SCOPE )}:registry=${u.href}`,
+			`//${hostPath}:_authToken=${token}`
+		].join( os.EOL ) + os.EOL;
+
+		if ( MODE === "env" ) {
+
+			// Write to a temp .npmrc and export env so the *current shell* can reuse it
+			const tmpFile = path.join(
+				os.tmpdir(),
+				`three-blocks-${Date.now()}-${Math.random().toString( 36 ).slice( 2 )}.npmrc`
+			);
+			fs.writeFileSync( tmpFile, npmrcContent, { mode: 0o600 } );
+
+			// Print shell exports; caller should `eval "$(npx -y three-blocks-login --mode env)"`
+			const maskedLicense = maskLicense( LICENSE_CLEAN );
+			renderEnvHeader( {
+				scope: SCOPE,
+				registry: u.href,
+				expiresAt,
+				tmpFile,
+				licenseMasked: maskedLicense,
+				licenseId,
+				channel: CHANNEL,
+				status: authStatus,
+				plan,
+				teamName,
+				teamId,
+				repository,
+				domain,
+				region,
+				userDisplayName: USER_DISPLAY_NAME,
+			} );
+			if ( PRINT_SHELL ) {
+
+				const exportLines = [
+					`export NPM_CONFIG_USERCONFIG=${quoteShell( tmpFile )}`,
+					`export npm_config_userconfig=${quoteShell( tmpFile )}`,
+					`export THREE_BLOCKS_CHANNEL=${quoteShell( CHANNEL )}`,
+				];
+				const summaryPrint = [
+					`cat <<'EOF'`,
+					`${plainBanner} scoped login ready (${authStatus.ok ? 'ok' : 'error'})`,
+					`  scope    : ${SCOPE}`,
+					`  registry : ${u.href}`,
+					`  expires  : ${expiresAt ?? 'unknown'}`,
+					`  license  : ${maskedLicense}`,
+					`  npmrc    : ${tmpFile}`,
+					`EOF`,
+				];
+				console.log( [ ...exportLines, '', ...summaryPrint ].join( '\n' ) );
+
+			} else {
+
+				log.info( `${plainBanner} temp npmrc ready. Use --print-shell to emit export commands.` );
+
+			}
+
+			return;
+
+		}
+
+		if ( MODE === "project" ) {
+
+			// Write to local ./.npmrc (recommend users gitignore this)
+			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"})` )}` );
+			return;
+
+		}
+
+		if ( MODE === "user" ) {
+
+			// Update user's npm config (requires npm on PATH)
+			await run( "npm", [ "config", "set", `${normalizeScope( SCOPE )}:registry`, u.href ] );
+			await run( "npm", [
+				"config",
+				"set",
+				`//${hostPath}:_authToken`,
+				token
+			] );
+			log.ok( `${banner} updated user npm config ${dim( `(${SCOPE} → ${u.href}, expires ${expiresAt ?? "unknown"})` )}` );
+			return;
+
+		}
+
+		fail(
+			`Unknown --mode "${MODE}". Use env | project | user.`,
+			{ suggestion: "Pass --mode env, --mode project, or --mode user." }
+		);
+
+	} catch ( error ) {
+
+		let err = error;
+		if ( err instanceof CliError === false ) {
+
+			const message = error?.message || String( error );
+			if ( /ByteString/i.test( message ) || /character at index/i.test( message ) ) {
+
+				err = new CliError(
+					"License appears malformed. Please copy your tb_… key exactly and retry.",
+					{ cause: error }
+				);
+
+			} else {
+
+				err = new CliError(
+					"Authentication failed. Please try again. Use --verbose or --debug for more details.",
+					{ cause: error }
+				);
+
+			}
+
+		}
+
+		log.error( `${banner} ${err.message}` );
+
+		const detail = ( err.stderr || err.stdout || "" ).trim();
+		if ( detail ) {
+
+			for ( const line of detail.split( /\r?\n/ ) ) {
+
+				console.error( dim( `    ${line}` ) );
+
+			}
+
+		}
+
+		if ( err.suggestion ) log.info( dim( `Hint: ${err.suggestion}` ) );
+		if ( DEBUG && err.cause && err.cause !== err && err.cause?.stack ) {
+
+			console.error( dim( err.cause.stack ) );
+
+		} else if ( DEBUG && err.stack ) {
+
+			console.error( dim( err.stack ) );
+
+		}
+
+		process.exit( err.exitCode ?? 1 );
+
+	}
+
+} )();
+
+function normalizeScope( scope ) {
+
+	return scope.startsWith( "@" ) ? scope : `@${scope}`;
+
 }
 
-function ensureTrailingSlash(url) {
-  return url.endsWith("/") ? url : url + "/";
+function ensureTrailingSlash( url ) {
+
+	return url.endsWith( "/" ) ? url : url + "/";
+
 }
 
-function loadEnvFromDotfile(dir) {
-  try {
-    const files = [path.join(dir, ".env.local"), path.join(dir, ".env")];
-    for (const file of files) {
-      if (!fs.existsSync(file)) continue;
-      const txt = fs.readFileSync(file, "utf8");
-      for (const raw of txt.split(/\r?\n/)) {
-        const line = raw.trim();
-        if (!line || line.startsWith("#")) continue;
-        const eq = line.indexOf("=");
-        if (eq === -1) continue;
-        const key = line.slice(0, eq).trim();
-        let val = line.slice(eq + 1).trim();
-        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-          val = val.slice(1, -1);
-        }
-        if (process.env[key] === undefined) process.env[key] = val;
-      }
-    }
-  } catch {}
+function loadEnvFromDotfile( dir ) {
+
+	try {
+
+		const files = [ path.join( dir, ".env.local" ), path.join( dir, ".env" ) ];
+		for ( const file of files ) {
+
+			if ( ! fs.existsSync( file ) ) continue;
+			const txt = fs.readFileSync( file, "utf8" );
+			for ( const raw of txt.split( /\r?\n/ ) ) {
+
+				const line = raw.trim();
+				if ( ! line || line.startsWith( "#" ) ) continue;
+				const eq = line.indexOf( "=" );
+				if ( eq === - 1 ) continue;
+				const key = line.slice( 0, eq ).trim();
+				let val = line.slice( eq + 1 ).trim();
+				if ( ( val.startsWith( '"' ) && val.endsWith( '"' ) ) || ( val.startsWith( "'" ) && val.endsWith( "'" ) ) ) {
+
+					val = val.slice( 1, - 1 );
+
+				}
+
+				if ( process.env[ key ] === undefined ) process.env[ key ] = val;
+
+			}
+
+		}
+
+	} catch {}
+
 }
 
-async function fetchToken(endpoint, license, channel) {
-  let url = endpoint;
-  try {
-    const u = new URL(endpoint);
-    if (!u.searchParams.get('channel')) u.searchParams.set('channel', channel);
-    url = u.toString();
-  } catch {}
-  const res = await fetch(url, {
-    method: "GET",
-    headers: {
-      "authorization": `Bearer ${license}`,
-      "accept": "application/json",
-      "x-three-blocks-channel": channel
-    }
-  });
-  if (!res.ok) {
-    let body = "";
-    try { body = await res.text(); } catch {}
-    if (VERBOSE) {
-      log.warn(`[debug] broker response: status=${res.status} body=${truncate(body, 300)}`);
-    }
-    let msg = "Request failed. Please try again.";
-    if (res.status === 401 || res.status === 403) {
-      msg = "Authentication failed. Verify your license or access rights.";
-    } else if (res.status === 404) {
-      msg = "Service not found or endpoint misconfigured.";
-    } else if (res.status === 429) {
-      msg = "Too many requests. Please retry later.";
-    } else if (res.status >= 500) {
-      msg = "Upstream service error. Please retry later.";
-    }
-    throw new Error(msg);
-  }
-  const json = await res.json();
-  // expected: { registry, token, expiresAt? }
-  return json;
+async function fetchToken( endpoint, license, channel ) {
+
+	let url = endpoint;
+	try {
+
+		const u = new URL( endpoint );
+		if ( ! u.searchParams.get( 'channel' ) ) u.searchParams.set( 'channel', channel );
+		url = u.toString();
+
+	} catch {}
+
+	logDebug( `GET ${url}` );
+	let res;
+	try {
+
+		res = await fetch( url, {
+			method: "GET",
+			headers: {
+				"authorization": `Bearer ${license}`,
+				"accept": "application/json",
+				"x-three-blocks-channel": channel
+			}
+		} );
+
+	} catch ( networkError ) {
+
+		throw new CliError(
+			"Could not reach the token broker endpoint.",
+			{
+				suggestion: "Check your network connection or override the endpoint with --endpoint.",
+				cause: networkError
+			}
+		);
+
+	}
+
+	let responseText = "";
+	try {
+
+		responseText = await res.text();
+
+	} catch ( readError ) {
+
+		logDebug( `Failed to read broker response body: ${readError?.message || readError}` );
+
+	}
+
+	if ( DEBUG ) {
+
+		logDebug( `Broker response status=${res.status} body=${truncate( responseText, 300 )}` );
+
+	}
+
+	if ( ! res.ok ) {
+
+		let suggestion = "Request failed. Please retry.";
+		if ( res.status === 401 || res.status === 403 ) {
+
+			suggestion = "Authentication failed. Verify your license or access rights.";
+
+		} else if ( res.status === 404 ) {
+
+			suggestion = "Service not found or endpoint misconfigured.";
+
+		} else if ( res.status === 429 ) {
+
+			suggestion = "Too many requests. Please retry later.";
+
+		} else if ( res.status >= 500 ) {
+
+			suggestion = "Upstream service error. Please retry later.";
+
+		}
+
+		throw new CliError(
+			`Token broker request failed (HTTP ${res.status}).`,
+			{
+				exitCode: 1,
+				stdout: responseText,
+				suggestion,
+			}
+		);
+
+	}
+
+	if ( ! responseText ) {
+
+		throw new CliError(
+			"Token broker returned an empty response.",
+			{
+				suggestion: "Retry in a few moments or contact support if the issue persists."
+			}
+		);
+
+	}
+
+	try {
+
+		const json = JSON.parse( responseText );
+		return json;
+
+	} catch ( parseError ) {
+
+		throw new CliError(
+			"Token broker returned invalid JSON.",
+			{
+				stdout: responseText,
+				suggestion: "Retry in a few moments or contact support if the issue persists.",
+				cause: parseError,
+			}
+		);
+
+	}
+
 }
 
-function truncate(s, n) {
-  if (!s) return s;
-  return s.length > n ? s.slice(0, n) + "…" : s;
+function truncate( s, n ) {
+
+	if ( ! s ) return s;
+	return s.length > n ? s.slice( 0, n ) + "…" : s;
+
 }
 
-function sanitizeLicense(x) {
-  if (!x) return "";
-  let s = String(x);
-  // Strip surrounding quotes
-  s = s.trim().replace(/^['"]+|['"]+$/g, "");
-  // Remove common pasted/hidden chars: bullet, zero-width, NBSP
-  s = s
-    .replace(/[\u2022\u2023\u25E6\u2043\u2219]/g, "") // bullets
-    .replace(/[\u200B-\u200D\uFEFF]/g, "")             // zero-width
-    .replace(/\u00A0/g, " ")                              // NBSP -> space
-    .replace(/\s+/g, "");                                 // remove whitespace
-  // Normalize fancy quotes to plain
-  s = s.replace(/[\u2018\u2019\u201C\u201D]/g, "");
-  return s;
+function sanitizeLicense( x ) {
+
+	if ( ! x ) return "";
+	let s = String( x );
+	// Strip surrounding quotes
+	s = s.trim().replace( /^['"]+|['"]+$/g, "" );
+	// Remove common pasted/hidden chars: bullet, zero-width, NBSP
+	s = s
+		.replace( /[\u2022\u2023\u25E6\u2043\u2219]/g, "" ) // bullets
+		.replace( /[\u200B-\u200D\uFEFF]/g, "" ) // zero-width
+		.replace( /\u00A0/g, " " ) // NBSP -> space
+		.replace( /\s+/g, "" ); // remove whitespace
+	// Normalize fancy quotes to plain
+	s = s.replace( /[\u2018\u2019\u201C\u201D]/g, "" );
+	return s;
+
 }
 
-function findFirstNonByteChar(s) {
-  if (!s) return -1;
-  for (let i = 0; i < s.length; i++) {
-    const code = s.charCodeAt(i);
-    if (code > 255) return i;
-  }
-  return -1;
+function findFirstNonByteChar( s ) {
+
+	if ( ! s ) return - 1;
+	for ( let i = 0; i < s.length; i ++ ) {
+
+		const code = s.charCodeAt( i );
+		if ( code > 255 ) return i;
+
+	}
+
+	return - 1;
+
 }
 
-function looksLikeLicense(s) {
-  if (!s) return false;
-  // tb_ followed by base64url-ish payload
-  return /^tb_[A-Za-z0-9_-]{10,}$/.test(s);
+function looksLikeLicense( s ) {
+
+	if ( ! s ) return false;
+	// tb_ followed by base64url-ish payload
+	return /^tb_[A-Za-z0-9_-]{10,}$/.test( s );
+
 }
 
-async function run(cmd, args) {
-  const { spawn } = await import("node:child_process");
-  return new Promise((resolve, reject) => {
-    const p = spawn(cmd, args, { stdio: "inherit", shell: true });
-    p.on("close", (code) => {
-      if (code === 0) resolve(undefined);
-      else reject(new Error(`${cmd} ${args.join(" ")} exited with ${code}`));
-    });
-  });
+async function run( cmd, args ) {
+
+	const { spawn } = await import( "node:child_process" );
+	const spawnArgs = Array.isArray( args ) ? args : [];
+	logDebug( `exec ${formatCommand( cmd, spawnArgs )}` );
+	return new Promise( ( resolve, reject ) => {
+
+		const child = spawn( cmd, spawnArgs, {
+			stdio: "inherit",
+			shell: process.platform === "win32",
+			env: process.env,
+		} );
+		child.on( "error", ( error ) => {
+
+			reject(
+				new CliError(
+					`Failed to start ${cmd}: ${error.message}`,
+					{ command: cmd, args: spawnArgs, cause: error }
+				)
+			);
+
+		} );
+		child.on( "close", ( code ) => {
+
+			if ( code === 0 ) resolve( undefined );
+			else {
+
+				reject(
+					new CliError(
+						`Command failed (${formatCommand( cmd, spawnArgs )}) [exit ${code}]`,
+						{ exitCode: code ?? 1, command: cmd, args: spawnArgs }
+					)
+				);
+
+			}
+
+		} );
+
+	} );
+
 }
 
-function parseArgs(argv) {
-  const out = {};
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (!a.startsWith("-")) continue;
-    const key = a.replace(/^-+/, "");
-    const next = argv[i + 1];
-    if (["--quiet", "-q"].includes(a)) out.quiet = true;
-    else if (["--verbose", "-v"].includes(a)) out.verbose = true;
-    else if (next && !next.startsWith("-")) {
-      out[key] = next;
-      i++;
-    } else {
-      out[key] = true;
-    }
-  }
-  return out;
+function parseArgs( argv ) {
+
+	const out = {};
+	for ( let i = 0; i < argv.length; i ++ ) {
+
+		const a = argv[ i ];
+		if ( ! a.startsWith( "-" ) ) continue;
+		const key = a.replace( /^-+/, "" );
+		const next = argv[ i + 1 ];
+		if ( [ "--quiet", "-q" ].includes( a ) ) out.quiet = true;
+		else if ( [ "--verbose", "-v" ].includes( a ) ) out.verbose = true;
+		else if ( next && ! next.startsWith( "-" ) ) {
+
+			out[ key ] = next;
+			i ++;
+
+		} else {
+
+			out[ key ] = true;
+
+		}
+
+	}
+
+	return out;
+
 }
 
-function fail(msg) {
-  console.error(`${red("✖")} ${banner} ${msg}`);
-  process.exit(1);
+function fail( msg, options = {} ) {
+
+	throw new CliError( msg, options );
+
 }