create-three-blocks-starter 0.0.5 → 0.0.7

package/bin/index.js

@@ -12,531 +12,998 @@ import { spawnSync } from 'node:child_process';
 import readline from 'node:readline';
 import { bold, cyan, dim, green, red, yellow } from 'kolorist';
 
-const ESC = (n) => `\u001b[${n}m`;
-const reset = ESC(0);
+const ESC = ( n ) => `\u001b[${n}m`;
+const reset = ESC( 0 );
 
-const STARTER_PKG = '@three-blocks/starter';   // private starter (lives in CodeArtifact)
-const LOGIN_CLI = 'three-blocks-login';        // public login CLI
+const STARTER_PKG = '@three-blocks/starter'; // private starter (lives in CodeArtifact)
+const LOGIN_CLI = 'three-blocks-login'; // public login CLI
+const LOGIN_SPEC = `${LOGIN_CLI}@latest`; // force-fresh npx install
 const SCOPE = '@three-blocks';
 
-const BLOCKED_NPM_ENV_KEYS = new Set([
-  'npm_config__three_blocks_registry',
-  'npm_config__three-blocks-registry',
-  'npm_config_verify_deps_before_run',
-  'npm_config_verify-deps-before-run',
-  'npm_config_global_bin_dir',
-  'npm_config_global-bin-dir',
-  'npm_config__jsr_registry',
-  'npm_config__jsr-registry',
-  'npm_config_node_linker',
-  'npm_config_node-linker',
-].map((key) => key.replace(/-/g, '_').toLowerCase()));
-
-const cleanNpmEnv = (extra = {}) => {
-  const env = { ...process.env, ...extra };
-  for (const key of Object.keys(env)) {
-    const normalized = key.replace(/-/g, '_').toLowerCase();
-    if (BLOCKED_NPM_ENV_KEYS.has(normalized)) {
-      delete env[key];
-    }
-  }
-  return env;
+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() ) );
+
+let DEBUG = /^1|true|yes$/i.test( String( process.env.THREE_BLOCKS_DEBUG || '' ).trim() );
+
+const logDebug = ( msg ) => {
+
+	if ( DEBUG ) console.log( dim( `▸ ${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 cleanNpmEnv = ( extra = {} ) => {
+
+	const env = { ...process.env, ...extra };
+	for ( const key of Object.keys( env ) ) {
+
+		const normalized = key.replace( /-/g, '_' ).toLowerCase();
+		if ( BLOCKED_NPM_ENV_KEYS.has( normalized ) ) {
+
+			delete env[ key ];
+
+		}
+
+	}
+
+	return env;
+
 };
 
 const STEP_ICON = '⏺ ';
-const logInfo = (msg) => { console.log(`${STEP_ICON}${msg}`); };
-const logProgress = (msg) => { console.log(`${cyan(STEP_ICON)}${msg}`); };
-const logSuccess = (msg) => { console.log(`${green(STEP_ICON)}${msg}`); };
-const logWarn = (msg) => { console.log(`${yellow(STEP_ICON)}${msg}`); };
-const logError = (msg) => { console.error(`${red(STEP_ICON)}${msg}`); };
-
-const die = (m) => { logError(m); process.exit(1); };
-const run = (cmd, args, opts = {}) => {
-  const r = spawnSync(cmd, args, { stdio: 'inherit', ...opts, env: cleanNpmEnv(opts.env) });
-  if (r.status !== 0) process.exit(r.status ?? 1);
+const logInfo = ( msg ) => {
+
+	console.log( `${STEP_ICON}${msg}` );
+
+};
+
+const logProgress = ( msg ) => {
+
+	console.log( `${cyan( STEP_ICON )}${msg}` );
+
+};
+
+const logSuccess = ( msg ) => {
+
+	console.log( `${green( STEP_ICON )}${msg}` );
+
+};
+
+const logWarn = ( msg ) => {
+
+	console.log( `${yellow( STEP_ICON )}${msg}` );
+
+};
+
+const logError = ( msg ) => {
+
+	console.error( `${red( STEP_ICON )}${msg}` );
+
+};
+
+const die = ( m ) => {
+
+	throw new CliError( m );
+
+};
+
+const run = ( cmd, args, opts = {} ) => {
+
+	const spawnArgs = Array.isArray( args ) ? args : [];
+	logDebug( `exec ${formatCommand( cmd, spawnArgs )}` );
+	const r = spawnSync( cmd, spawnArgs, { stdio: 'inherit', ...opts, env: cleanNpmEnv( opts.env ) } );
+	if ( r.error ) {
+
+		throw new CliError(
+			`Failed to start ${cmd}: ${r.error.message}`,
+			{ command: cmd, args: spawnArgs, cause: r.error }
+		);
+
+	}
+
+	if ( r.status !== 0 ) {
+
+		throw new CliError(
+			`Command failed (${formatCommand( cmd, spawnArgs )}) [exit ${r.status}]`,
+			{ exitCode: r.status ?? 1, command: cmd, args: spawnArgs, stdout: r.stdout ? r.stdout.toString() : '' }
+		);
+
+	}
+
+	return r;
+
 };
 
 // capture stdout (used for npm pack)
-const exec = (cmd, args, opts = {}) => {
-  const r = spawnSync(cmd, args, { stdio: ['ignore', 'pipe', 'inherit'], ...opts, env: cleanNpmEnv(opts.env) });
-  if (r.status !== 0) process.exit(r.status ?? 1);
-  return (r.stdout || Buffer.alloc(0)).toString();
+const exec = ( cmd, args, opts = {} ) => {
+
+	const spawnArgs = Array.isArray( args ) ? args : [];
+	logDebug( `exec ${formatCommand( cmd, spawnArgs )}` );
+	const r = spawnSync( cmd, spawnArgs, { stdio: [ 'ignore', 'pipe', 'pipe' ], ...opts, env: cleanNpmEnv( opts.env ) } );
+	const stdout = r.stdout ? r.stdout.toString() : '';
+	const stderr = r.stderr ? r.stderr.toString() : '';
+	if ( r.error ) {
+
+		throw new CliError(
+			`Failed to start ${cmd}: ${r.error.message}`,
+			{ command: cmd, args: spawnArgs, stdout, stderr, cause: r.error }
+		);
+
+	}
+
+	if ( r.status !== 0 ) {
+
+		throw new CliError(
+			`Command failed (${formatCommand( cmd, spawnArgs )}) [exit ${r.status}]`,
+			{ exitCode: r.status ?? 1, command: cmd, args: spawnArgs, stdout, stderr }
+		);
+
+	}
+
+	if ( stderr.trim() ) logDebug( `stderr ${formatCommand( cmd, spawnArgs )}\n${stderr.trim()}` );
+	return stdout;
+
 };
 
-async function ensureEmptyDir(dir) {
-  try { await fsp.mkdir(dir, { recursive: true }); } catch {}
-  const files = await fsp.readdir(dir).catch(() => []);
-  if (files.length) die(`Target directory '${path.basename(dir)}' is not empty.`);
+async function ensureEmptyDir( dir ) {
+
+	try {
+
+		await fsp.mkdir( dir, { recursive: true } );
+
+	} catch {}
+
+	const files = await fsp.readdir( dir ).catch( () => [] );
+	if ( files.length ) die( `Target directory '${path.basename( dir )}' is not empty.` );
+
 }
 
-async function promptHidden(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 === '\u0008' || ch === '\u007f') {
-          if (value.length) {
-            value = value.slice(0, -1);
-            readline.moveCursor(stdout, -1, 0);
-            stdout.write(' ');
-            readline.moveCursor(stdout, -1, 0);
-          }
-          continue;
-        }
-        // Ignore ESC start of control sequences
-        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);
-  });
+async function promptHidden( 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 === '\u0008' || ch === '\u007f' ) {
+
+					if ( value.length ) {
+
+						value = value.slice( 0, - 1 );
+						readline.moveCursor( stdout, - 1, 0 );
+						stdout.write( ' ' );
+						readline.moveCursor( stdout, - 1, 0 );
+
+					}
+
+					continue;
+
+				}
+
+				// Ignore ESC start of control sequences
+				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 );
+
+	} );
+
 }
 
-function mkTmpDir(prefix = 'three-blocks-') {
-  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+function mkTmpDir( prefix = 'three-blocks-' ) {
+
+	return fs.mkdtempSync( path.join( os.tmpdir(), prefix ) );
+
 }
 
-function mask(s) {
-  if (!s) return '';
-  const v = String(s);
-  if (v.length <= 6) return '••••';
-  return v.slice(0, 3) + '••••' + v.slice(-4);
+function mask( s ) {
+
+	if ( ! s ) return '';
+	const v = String( s );
+	if ( v.length <= 6 ) return '••••';
+	return v.slice( 0, 3 ) + '••••' + v.slice( - 4 );
+
 }
 
-const BROKER_DEFAULT_ENDPOINT = process.env.THREE_BLOCKS_BROKER_URL || 'http://localhost:3000/api/npm/token';
-
-const resolveBrokerEndpoint = (channel) => {
-  let endpoint = BROKER_DEFAULT_ENDPOINT;
-  try {
-    const u = new URL(endpoint);
-    if (channel && !u.searchParams.get('channel')) {
-      u.searchParams.set('channel', channel);
-    }
-    endpoint = u.toString();
-  } catch {}
-  return endpoint;
+const BROKER_DEFAULT_ENDPOINT = process.env.THREE_BLOCKS_BROKER_URL || 'https://www.threejs-blocks.com/api/npm/token';
+
+const resolveBrokerEndpoint = ( channel ) => {
+
+	let endpoint = BROKER_DEFAULT_ENDPOINT;
+	try {
+
+		const u = new URL( endpoint );
+		if ( channel && ! u.searchParams.get( 'channel' ) ) {
+
+			u.searchParams.set( 'channel', channel );
+
+		}
+
+		endpoint = u.toString();
+
+	} catch {}
+
+	return endpoint;
+
 };
 
-const fetchTokenMetadata = async (license, channel) => {
-  if (!license || typeof fetch !== 'function') return null;
-  const endpoint = resolveBrokerEndpoint(channel);
-  try {
-    const res = await fetch(endpoint, {
-      method: 'GET',
-      headers: {
-        authorization: `Bearer ${license}`,
-        accept: 'application/json',
-        'x-three-blocks-channel': channel,
-      },
-    });
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}`);
-    }
-    return await res.json();
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    logWarn(`Continuing without token metadata (${msg})`);
-    return null;
-  }
+const fetchTokenMetadata = async ( license, channel ) => {
+
+	if ( ! license || typeof fetch !== 'function' ) return null;
+	const endpoint = resolveBrokerEndpoint( channel );
+	try {
+
+		const res = await fetch( endpoint, {
+			method: 'GET',
+			headers: {
+				authorization: `Bearer ${license}`,
+				accept: 'application/json',
+				'x-three-blocks-channel': channel,
+			},
+		} );
+		if ( ! res.ok ) {
+
+			throw new Error( `HTTP ${res.status}` );
+
+		}
+
+		return await res.json();
+
+	} catch ( err ) {
+
+		const msg = err instanceof Error ? err.message : String( err );
+		logWarn( `Continuing without token metadata (${msg})` );
+		return null;
+
+	}
+
 };
 
-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 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 HEADER_WIDTH = 118;
 const LEFT_WIDTH = 72;
 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 remaining = width - visibleLength(text);
-  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 remaining = width - visibleLength( text );
+	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);
-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 );
+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 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 formatFirstName = (value) => {
-  const name = String(value || '').trim();
-  if (!name) return '';
-  const first = name.split(/\s+/)[0];
-  return capitalize(first);
+const formatFirstName = ( value ) => {
+
+	const name = String( value || '' ).trim();
+	if ( ! name ) return '';
+	const first = name.split( /\s+/ )[ 0 ];
+	return capitalize( first );
+
 };
 
 const getUserDisplayName = () => {
-  const candidate = process.env.THREE_BLOCKS_USER_NAME
+
+	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 inferPlan = (license) => {
-  if (!license) return 'Unknown plan';
-  if (/live/i.test(license)) return 'Pro Plan';
-  if (/test/i.test(license)) return 'Sandbox Plan';
-  if (/beta/i.test(license)) return 'Beta Plan';
-  return 'Developer Plan';
+const inferPlan = ( license ) => {
+
+	if ( ! license ) return 'Unknown plan';
+	if ( /live/i.test( license ) ) return 'Pro Plan';
+	if ( /test/i.test( license ) ) return 'Sandbox Plan';
+	if ( /beta/i.test( license ) ) return 'Beta Plan';
+	return 'Developer Plan';
+
 };
 
-const extractVersionFromTarball = (filename) => {
-  if (!filename) return '';
-  const match = filename.match(/-(\d+\.\d+\.\d+(?:-[^.]*)?)\.tgz$/);
-  return match ? match[1] : '';
+const extractVersionFromTarball = ( filename ) => {
+
+	if ( ! filename ) return '';
+	const match = filename.match( /-(\d+\.\d+\.\d+(?:-[^.]*)?)\.tgz$/ );
+	return match ? match[ 1 ] : '';
+
 };
 
-const renderHeader = ({
-  starterVersion,
-  userDisplayName,
-  planName,
-  repoPath,
-  projectName,
-  channel,
-  coreVersion,
-  license,
-  registry,
-  domain,
-  region,
-  repository,
-  expiresAt,
-  teamId,
-  teamName,
-  licenseId,
-}) => {
-  const welcome = userDisplayName ? `Welcome back ${userDisplayName}!` : 'Welcome!';
-  const normalizedPlan = planName || 'Unknown plan';
-  const resolvedTeamName = teamName || teamId || '';
-  const planSuffix = resolvedTeamName ? ` · Team: ${resolvedTeamName}` : '';
-  const planLine = `@three-blocks/core ${coreVersion || (channel === 'stable' ? 'latest' : channel)} · ${normalizedPlan}${planSuffix}`;
-  const channelDisplay = (channel || 'stable').toUpperCase();
-  const channelLine = `Channel: ${channelDisplay}${region ? ` · Region: ${region}` : ''}`;
-  const repositoryLineBase = repository ? `Repository: ${repository}` : 'Repository: —';
-  const registryShort = formatRegistryShort(registry);
-  const repositoryLine = registryShort ? `${repositoryLineBase} → ${registryShort}` : repositoryLineBase;
-  const registryLine = `Registry: ${registryShort || '—'}`;
-  const licenseLine = `License: ${mask(license)}${licenseId ? ` · ${licenseId}` : ''}`;
-  const expiresLine = formatExpiryLabel(expiresAt);
-  const projectLabel = projectName || path.basename(repoPath);
-  const projectLine = `Project: ${projectLabel}`;
-  const domainLine = domain ? `Domain: ${domain}` : '';
-  const regionLine = region ? `Region: ${region}` : '';
-  const title = `─── Three.js Blocks Starter v${starterVersion || '?.?.?'} `;
-  const separatorRow = makeHeaderRow(repeatChar('─', LEFT_WIDTH), repeatChar('─', RIGHT_WIDTH));
-  const ascii = [
-    'THREE.JS',
-    ' ______     __         ______     ______     __  __     ______   ',
-    '/\\  == \\   /\\ \\       /\\  __ \\   /\\  ___\\   /\\ \\/ /    /\\  ___\\  ',
-    '\\ \\  __<   \\ \\ \\____  \\ \\ \\/\\ \\  \\ \\ \\____  \\ \\  _"-.  \\ \\___  \\ ',
-    ' \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_\\ \\_\\  \\/\\_____\\',
-    '  \\/_____\/   \\/_____/   \\/_____/   \\/_____/   \\/_/ \/_/   \\/_____/'
-  ];
-  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(welcome, projectLine, 'center', 'center')),
-    applyHeaderColor(separatorRow, { keepContentYellow: true }),
-    applyHeaderColor(makeHeaderRow(planLine, channelLine)),
-    applyHeaderColor(makeHeaderRow(repositoryLine, registryLine)),
-    ...(domainLine || regionLine ? [applyHeaderColor(makeHeaderRow(domainLine || '', regionLine, 'left', 'center'))] : []),
-    applyHeaderColor(makeHeaderRow(licenseLine, expiresLine)),
-    applyHeaderColor(`╰${repeatChar('─', HEADER_WIDTH - 2)}╯`, { keepContentYellow: true }),
-  ];
-  for (const row of lines) console.log(row);
+const renderHeader = ( {
+	starterVersion,
+	userDisplayName,
+	planName,
+	repoPath,
+	projectName,
+	channel,
+	coreVersion,
+	license,
+	registry,
+	domain,
+	region,
+	repository,
+	expiresAt,
+	teamId,
+	teamName,
+	licenseId,
+} ) => {
+
+	const welcome = userDisplayName ? `Welcome back ${userDisplayName}!` : 'Welcome!';
+	const normalizedPlan = planName || 'Unknown plan';
+	const resolvedTeamName = teamName || teamId || '';
+	const planSuffix = resolvedTeamName ? ` · Team: ${resolvedTeamName}` : '';
+	const planLine = `@three-blocks/core ${coreVersion || ( channel === 'stable' ? 'latest' : channel )} · ${normalizedPlan}${planSuffix}`;
+	const channelDisplay = ( channel || 'stable' ).toUpperCase();
+	const channelLine = `Channel: ${channelDisplay}${region ? ` · Region: ${region}` : ''}`;
+	const repositoryLineBase = repository ? `Repository: ${repository}` : 'Repository: —';
+	const registryShort = formatRegistryShort( registry );
+	const repositoryLine = registryShort ? `${repositoryLineBase} → ${registryShort}` : repositoryLineBase;
+	const registryLine = `Registry: ${registryShort || '—'}`;
+	const licenseLine = `License: ${mask( license )}${licenseId ? ` · ${licenseId}` : ''}`;
+	const expiresLine = formatExpiryLabel( expiresAt );
+	const projectLabel = projectName || path.basename( repoPath );
+	const projectLine = `Project: ${projectLabel}`;
+	const domainLine = domain ? `Domain: ${domain}` : '';
+	const regionLine = region ? `Region: ${region}` : '';
+	const title = `─── Three.js Blocks Starter v${starterVersion || '?.?.?'} `;
+	const separatorRow = makeHeaderRow( repeatChar( '─', LEFT_WIDTH ), repeatChar( '─', RIGHT_WIDTH ) );
+	const ascii = [
+		'THREE.JS',
+		' ______     __         ______     ______     __  __     ______   ',
+		'/\\  == \\   /\\ \\       /\\  __ \\   /\\  ___\\   /\\ \\/ /    /\\  ___\\  ',
+		'\\ \\  __<   \\ \\ \\____  \\ \\ \\/\\ \\  \\ \\ \\____  \\ \\  _"-.  \\ \\___  \\ ',
+		' \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_____\\  \\ \\_\\ \\_\\  \\/\\_____\\',
+		'  \\/_____\/   \\/_____/   \\/_____/   \\/_____/   \\/_/ \/_/   \\/_____/'
+	];
+	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( welcome, projectLine, 'center', 'center' ) ),
+		applyHeaderColor( separatorRow, { keepContentYellow: true } ),
+		applyHeaderColor( makeHeaderRow( planLine, channelLine ) ),
+		applyHeaderColor( makeHeaderRow( repositoryLine, registryLine ) ),
+		...( domainLine || regionLine ? [ applyHeaderColor( makeHeaderRow( domainLine || '', regionLine, 'left', 'center' ) ) ] : [] ),
+		applyHeaderColor( makeHeaderRow( licenseLine, expiresLine ) ),
+		applyHeaderColor( `╰${repeatChar( '─', HEADER_WIDTH - 2 )}╯`, { keepContentYellow: true } ),
+	];
+	for ( const row of lines ) console.log( row );
+
 };
 
 async function main() {
-  const args = process.argv.slice(2);
-  let appName = '';
-  let channel = String(process.env.THREE_BLOCKS_CHANNEL || 'stable').toLowerCase();
-  const userDisplayName = getUserDisplayName();
-  const repoPath = process.cwd();
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (!a.startsWith('-') && !appName) { appName = a; continue; }
-    if (a === '--channel' || a === '-c') { const v = args[i + 1]; if (v) { channel = String(v).toLowerCase(); i++; } continue; }
-    const m = a.match(/^--channel=(.+)$/);
-    if (m) { channel = String(m[1]).toLowerCase(); continue; }
-  }
-  if (!['stable', 'beta', 'alpha'].includes(channel)) channel = 'stable';
-  if (!appName) {
-    die(
-      `Usage:\n` +
-      `  THREE_BLOCKS_SECRET_KEY=sk_live_... npx three-blocks-create-app <directory>\n` +
-      `  (or: npx three-blocks-create-app <directory> and enter the key when prompted)`
-    );
-  }
-
-  const targetDir = path.resolve(process.cwd(), appName);
-  await ensureEmptyDir(targetDir);
-
-  // 1) License key (env or prompt)
-  let license = process.env.THREE_BLOCKS_SECRET_KEY;
-  if (license) {
-    logInfo(`Using ${bold('THREE_BLOCKS_SECRET_KEY')} from environment ${dim(`(${mask(license)})`)}`);
-  } else {
-    console.log('');
-    logInfo(bold(cyan('Three Blocks Starter')) + ' ' + dim(`[channel: ${channel}]`));
-    logInfo(dim('Enter your license key to continue.'));
-    logInfo(dim('Tip: paste it here; input is hidden. Press Enter to submit.'));
-    license = await promptHidden(`${STEP_ICON}${bold('License key')} ${dim('(tb_…)')}: `);
-    if (!license) die('License key is required to install private packages.');
-  }
-  let planName = inferPlan(license);
-  const tokenMetadata = await fetchTokenMetadata(license, channel);
-  let headerChannel = channel;
-  if (tokenMetadata?.channel) {
-    const maybeChannel = String(tokenMetadata.channel).toLowerCase();
-    if (['stable', 'beta', 'alpha'].includes(maybeChannel)) headerChannel = maybeChannel;
-  }
-  if (tokenMetadata?.plan) {
-    const label = formatPlanLabel(tokenMetadata.plan);
-    if (label) {
-      planName = label.toLowerCase().includes('plan') ? label : `${label} Plan`;
-    }
-  }
-  let headerRegistry = tokenMetadata?.registry ? String(tokenMetadata.registry) : '';
-  const headerDomain = tokenMetadata?.domain ? String(tokenMetadata.domain) : '';
-  const headerRegion = tokenMetadata?.region ? String(tokenMetadata.region) : '';
-  const headerRepository = tokenMetadata?.repository ? String(tokenMetadata.repository) : '';
-  const headerExpires = tokenMetadata?.expiresAt ?? tokenMetadata?.expiresAtIso ?? null;
-  const headerTeamId = tokenMetadata?.teamId ? String(tokenMetadata.teamId) : '';
-  const headerTeamName = tokenMetadata?.teamName ? String(tokenMetadata.teamName) : '';
-  const headerLicenseId = tokenMetadata?.licenseId ? String(tokenMetadata.licenseId) : '';
-
-  // 2) Pre-login in a TEMP dir to generate a temp .npmrc (no always-auth)
-  const tmp = mkTmpDir();
-  const tmpNpmrc = path.join(tmp, '.npmrc');
-  logProgress(`Fetching short-lived token (temp .npmrc) [channel: ${channel}] ...`);
-  run('npx', ['-y', LOGIN_CLI, '--mode', 'project', '--scope', SCOPE, '--channel', channel], {
-    cwd: tmp,
-    env: { ...process.env, THREE_BLOCKS_SECRET_KEY: license, THREE_BLOCKS_CHANNEL: channel },
-  });
-  if (!fs.existsSync(tmpNpmrc)) die('Login failed: temp .npmrc not created.');
-  // Extract registry URL from temp .npmrc so we can pass it explicitly to npm create
-  let registryUrl = '';
-  try {
-    const txt = fs.readFileSync(tmpNpmrc, 'utf8');
-    const m = txt.match(/^@[^:]+:registry=(.+)$/m);
-    if (m && m[1]) registryUrl = m[1].trim();
-  } catch {}
-  if (!headerRegistry && registryUrl) headerRegistry = registryUrl;
-
-  // 3) Scaffold the private starter by packing and extracting the tarball (avoids npm create naming transform)
-  const starterSpec = `${STARTER_PKG}@${channel === 'stable' ? 'latest' : channel}`;
-  logProgress(`Fetching starter tarball ${starterSpec} ...`);
-  const createEnv = {
-    ...process.env,
-    THREE_BLOCKS_SECRET_KEY: license,
-    NPM_CONFIG_USERCONFIG: tmpNpmrc,
-    npm_config_userconfig: tmpNpmrc,
-  };
-  let packedOut = exec('npm', ['pack', starterSpec, '--json', '--silent'], { cwd: tmp, env: createEnv });
-  let tarName = '';
-  let starterVersion = '';
-  try {
-    const info = JSON.parse(packedOut);
-    if (Array.isArray(info)) {
-      tarName = info[0]?.filename || '';
-      starterVersion = info[0]?.version || '';
-    } else {
-      tarName = info.filename || '';
-      starterVersion = info.version || '';
-    }
-  } catch {
-    const lines = String(packedOut || '').trim().split(/\r?\n/);
-    tarName = lines[lines.length - 1] || '';
-  }
-  const tarPath = path.join(tmp, tarName);
-  if (!tarName || !fs.existsSync(tarPath)) die('Failed to fetch starter tarball.');
-  const headerStarterVersion = starterVersion || extractVersionFromTarball(tarName);
-  const headerCoreVersion = headerChannel === 'stable' ? 'latest' : headerChannel;
-  renderHeader({
-    starterVersion: headerStarterVersion,
-    userDisplayName,
-    planName,
-    repoPath,
-    projectName: appName,
-    channel: headerChannel,
-    coreVersion: headerCoreVersion,
-    license,
-    registry: headerRegistry,
-    domain: headerDomain,
-    region: headerRegion,
-    repository: headerRepository,
-    expiresAt: headerExpires,
-    teamId: headerTeamId,
-    teamName: headerTeamName,
-    licenseId: headerLicenseId,
-  });
-  logProgress('Extracting files ...');
-  run('tar', ['-xzf', tarPath, '-C', targetDir, '--strip-components=1']);
-
-  // 4) Write .env.local and .gitignore entries
-  await fsp.writeFile(path.join(targetDir, '.env.local'),
-    `THREE_BLOCKS_SECRET_KEY=${license}\nTHREE_BLOCKS_CHANNEL=${channel}\n`, { mode: 0o600 }).catch(() => {});
-  const giPath = path.join(targetDir, '.gitignore');
-  let gi = '';
-  try { gi = await fsp.readFile(giPath, 'utf8'); } catch {}
-  for (const line of ['.env.local', '.npmrc']) {
-    if (!gi.includes(line)) gi += (gi.endsWith('\n') || gi === '' ? '' : '\n') + line + '\n';
-  }
-  await fsp.writeFile(giPath, gi);
-
-  // 5) First install — the starter already has:
-  //    "preinstall": "npx -y three-blocks-login --mode project --scope @three-blocks"
-  //    so it will mint a fresh token and write a project .npmrc.
-  try {
-    const pkgPath = path.join(targetDir, 'package.json');
-    const pkgRaw = await fsp.readFile(pkgPath, 'utf8');
-    const pkg = JSON.parse(pkgRaw);
-    pkg.scripts = pkg.scripts || {};
-    if (!pkg.scripts.preinstall) {
-      pkg.scripts.preinstall = `npx -y ${LOGIN_CLI} --mode project --scope ${SCOPE} --channel ${channel}`;
-    }
-    await fsp.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
-    logSuccess('Added preinstall to generated package.json to refresh token on installs.');
-  } catch (e) {
-    logWarn(`Warning: could not add preinstall to package.json: ${e?.message || String(e)}`);
-  }
-
-  logProgress('Installing dependencies (preinstall will refresh token) ...');
-  const hasPnpm = spawnSync('pnpm', ['-v'], { stdio: 'ignore' }).status === 0;
-  run(hasPnpm ? 'pnpm' : 'npm', [hasPnpm ? 'install' : 'ci'], {
-    cwd: targetDir,
-    env: {
-      ...process.env,
-      THREE_BLOCKS_SECRET_KEY: license,
-      THREE_BLOCKS_CHANNEL: channel,
-    },
-  });
-
-  {
-    const coreSpec = `@three-blocks/core@${channel === 'stable' ? 'latest' : channel}`;
-    logProgress(`Installing ${coreSpec} ...`);
-    const addArgs = hasPnpm ? ['add', '--save-exact', coreSpec] : ['install', '--save-exact', coreSpec];
-    const r = spawnSync(hasPnpm ? 'pnpm' : 'npm', addArgs, {
-      stdio: 'inherit',
-      cwd: targetDir,
-      env: {
-        ...process.env,
-        THREE_BLOCKS_SECRET_KEY: license,
-        THREE_BLOCKS_CHANNEL: channel,
-      },
-    });
-    if (r.status !== 0) {
-      logWarn(`Warning: could not install @three-blocks/core (exit ${r.status}).`);
-    }
-  }
-
-  // 6) Cleanup temp dir
-  try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {}
-
-  console.log('');
-  logSuccess(`${appName} is ready.`);
-  console.log('');
-  logInfo('Next:');
-  console.log(`  cd ${appName}`);
-  console.log(`  ${hasPnpm ? 'pnpm dev' : 'npm run dev'}`);
-  console.log('');
-  logInfo('Notes:');
-  console.log(`  • Your license key is stored in .env.local (gitignored).`);
-  console.log(`  • ${SCOPE} packages are private; each install refreshes a short-lived token via preinstall.`);
+
+	const args = process.argv.slice( 2 );
+	let appName = '';
+	let channel = String( process.env.THREE_BLOCKS_CHANNEL || 'stable' ).toLowerCase();
+	let debug = DEBUG;
+	const userDisplayName = getUserDisplayName();
+	const repoPath = process.cwd();
+	for ( let i = 0; i < args.length; i ++ ) {
+
+		const a = args[ i ];
+		if ( ! a.startsWith( '-' ) && ! appName ) {
+
+			appName = a; continue;
+
+		}
+
+		if ( a === '--debug' || a === '-d' ) {
+
+			debug = true; continue;
+
+		}
+
+		if ( a === '--channel' || a === '-c' ) {
+
+			const v = args[ i + 1 ]; if ( v ) {
+
+				channel = String( v ).toLowerCase(); i ++;
+
+			}
+
+			continue;
+
+		}
+
+		const m = a.match( /^--channel=(.+)$/ );
+		if ( m ) {
+
+			channel = String( m[ 1 ] ).toLowerCase(); continue;
+
+		}
+
+	}
+
+	DEBUG = debug;
+	if ( DEBUG ) logDebug( 'Debug logging enabled.' );
+
+	if ( ! [ 'stable', 'beta', 'alpha' ].includes( channel ) ) channel = 'stable';
+	if ( ! appName ) {
+
+		die(
+			`Usage:\n` +
+      `  THREE_BLOCKS_SECRET_KEY=sk_live_... npx create-three-blocks-starter <directory> [--channel <stable|beta|alpha>]\n` +
+      `  npx create-three-blocks-starter <directory> (will prompt for the license key)\n` +
+      `  Add --debug for verbose logging.`
+		);
+
+	}
+
+	const targetDir = path.resolve( process.cwd(), appName );
+	await ensureEmptyDir( targetDir );
+
+	// 1) License key (env or prompt)
+	let license = process.env.THREE_BLOCKS_SECRET_KEY;
+	if ( license ) {
+
+		logInfo( `Using ${bold( 'THREE_BLOCKS_SECRET_KEY' )} from environment ${dim( `(${mask( license )})` )}` );
+
+	} else {
+
+		console.log( '' );
+		logInfo( bold( cyan( 'Three Blocks Starter' ) ) + ' ' + dim( `[channel: ${channel}]` ) );
+		logInfo( dim( 'Enter your license key to continue.' ) );
+		logInfo( dim( 'Tip: paste it here; input is hidden. Press Enter to submit.' ) );
+		license = await promptHidden( `${STEP_ICON}${bold( 'License key' )} ${dim( '(tb_…)' )}: ` );
+		if ( ! license ) die( 'License key is required to install private packages.' );
+
+	}
+
+	let planName = inferPlan( license );
+	const tokenMetadata = await fetchTokenMetadata( license, channel );
+	let headerChannel = channel;
+	if ( tokenMetadata?.channel ) {
+
+		const maybeChannel = String( tokenMetadata.channel ).toLowerCase();
+		if ( [ 'stable', 'beta', 'alpha' ].includes( maybeChannel ) ) headerChannel = maybeChannel;
+
+	}
+
+	if ( tokenMetadata?.plan ) {
+
+		const label = formatPlanLabel( tokenMetadata.plan );
+		if ( label ) {
+
+			planName = label.toLowerCase().includes( 'plan' ) ? label : `${label} Plan`;
+
+		}
+
+	}
+
+	let headerRegistry = tokenMetadata?.registry ? String( tokenMetadata.registry ) : '';
+	const headerDomain = tokenMetadata?.domain ? String( tokenMetadata.domain ) : '';
+	const headerRegion = tokenMetadata?.region ? String( tokenMetadata.region ) : '';
+	const headerRepository = tokenMetadata?.repository ? String( tokenMetadata.repository ) : '';
+	const headerExpires = tokenMetadata?.expiresAt ?? tokenMetadata?.expiresAtIso ?? null;
+	const headerTeamId = tokenMetadata?.teamId ? String( tokenMetadata.teamId ) : '';
+	const headerTeamName = tokenMetadata?.teamName ? String( tokenMetadata.teamName ) : '';
+	const headerLicenseId = tokenMetadata?.licenseId ? String( tokenMetadata.licenseId ) : '';
+
+	// 2) Pre-login in a TEMP dir to generate a temp .npmrc (no always-auth)
+	let tmp = '';
+	let tmpNpmrc = '';
+	try {
+
+		tmp = mkTmpDir();
+		tmpNpmrc = path.join( tmp, '.npmrc' );
+		logProgress( `Fetching short-lived token (temp .npmrc) [channel: ${channel}] ...` );
+		try {
+
+			run( 'npx', [ '-y', LOGIN_SPEC, '--mode', 'project', '--scope', SCOPE, '--channel', channel ], {
+				cwd: tmp,
+				env: { ...process.env, THREE_BLOCKS_SECRET_KEY: license, THREE_BLOCKS_CHANNEL: channel },
+			} );
+
+		} catch ( err ) {
+
+			if ( err instanceof CliError ) {
+
+				throw new CliError(
+					'Login failed while minting short-lived token.',
+					{
+						exitCode: err.exitCode,
+						command: err.command,
+						args: err.args,
+						suggestion: 'Ensure the three-blocks-login CLI is reachable and your license key is valid.',
+						cause: err,
+					}
+				);
+
+			}
+
+			throw err;
+
+		}
+
+		if ( ! fs.existsSync( tmpNpmrc ) ) {
+
+			throw new CliError( 'Login failed: temp .npmrc not created.' );
+
+		}
+
+		// Extract registry URL from temp .npmrc so we can pass it explicitly to npm create
+		let registryUrl = '';
+		try {
+
+			const txt = fs.readFileSync( tmpNpmrc, 'utf8' );
+			const m = txt.match( /^@[^:]+:registry=(.+)$/m );
+			if ( m && m[ 1 ] ) registryUrl = m[ 1 ].trim();
+
+		} catch ( readErr ) {
+
+			logDebug( `Could not read temp .npmrc: ${readErr?.message || readErr}` );
+
+		}
+
+		if ( ! headerRegistry && registryUrl ) headerRegistry = registryUrl;
+
+		// 3) Scaffold the private starter by packing and extracting the tarball (avoids npm create naming transform)
+		const starterSpec = `${STARTER_PKG}@${channel === 'stable' ? 'latest' : channel}`;
+		logProgress( `Fetching starter tarball ${starterSpec} ...` );
+		const createEnv = {
+			...process.env,
+			THREE_BLOCKS_SECRET_KEY: license,
+			NPM_CONFIG_USERCONFIG: tmpNpmrc,
+			npm_config_userconfig: tmpNpmrc,
+		};
+		const packArgs = [ 'pack', starterSpec, '--json' ];
+		if ( ! DEBUG ) packArgs.push( '--silent' );
+		let packedOut = '';
+		try {
+
+			packedOut = exec( 'npm', packArgs, { cwd: tmp, env: createEnv } );
+
+		} catch ( err ) {
+
+			if ( err instanceof CliError ) {
+
+				const baseMessage = `Failed to fetch starter tarball ${starterSpec}.`;
+				const detail = ( err.stderr || err.stdout || '' ).trim();
+				const message = detail ? baseMessage : `${baseMessage} ${err.message || ''}`.trim();
+				throw new CliError(
+					message,
+					{
+						exitCode: err.exitCode,
+						command: err.command,
+						args: err.args,
+						stdout: err.stdout,
+						stderr: err.stderr,
+						suggestion: 'Confirm your license has access to the selected channel and that the package version exists.',
+						cause: err,
+					}
+				);
+
+			}
+
+			throw new CliError(
+				`Failed to fetch starter tarball ${starterSpec}.`,
+				{ cause: err }
+			);
+
+		}
+
+		let tarName = '';
+		let starterVersion = '';
+		try {
+
+			const info = JSON.parse( packedOut );
+			if ( Array.isArray( info ) ) {
+
+				tarName = info[ 0 ]?.filename || '';
+				starterVersion = info[ 0 ]?.version || '';
+
+			} else {
+
+				tarName = info.filename || '';
+				starterVersion = info.version || '';
+
+			}
+
+		} catch {
+
+			const lines = String( packedOut || '' ).trim().split( /\r?\n/ );
+			tarName = lines[ lines.length - 1 ] || '';
+
+		}
+
+		const tarPath = path.join( tmp, tarName );
+		if ( ! tarName || ! fs.existsSync( tarPath ) ) {
+
+			throw new CliError(
+				`Failed to fetch starter tarball ${starterSpec}.`,
+				{ suggestion: 'Ensure the requested release is published and accessible for your channel.' }
+			);
+
+		}
+
+		const headerStarterVersion = starterVersion || extractVersionFromTarball( tarName );
+		const headerCoreVersion = headerChannel === 'stable' ? 'latest' : headerChannel;
+		renderHeader( {
+			starterVersion: headerStarterVersion,
+			userDisplayName,
+			planName,
+			repoPath,
+			projectName: appName,
+			channel: headerChannel,
+			coreVersion: headerCoreVersion,
+			license,
+			registry: headerRegistry,
+			domain: headerDomain,
+			region: headerRegion,
+			repository: headerRepository,
+			expiresAt: headerExpires,
+			teamId: headerTeamId,
+			teamName: headerTeamName,
+			licenseId: headerLicenseId,
+		} );
+		logProgress( 'Extracting files ...' );
+		try {
+
+			run( 'tar', [ '-xzf', tarPath, '-C', targetDir, '--strip-components=1' ] );
+
+		} catch ( err ) {
+
+			if ( err instanceof CliError ) {
+
+				throw new CliError(
+					'Failed to extract starter files.',
+					{
+						exitCode: err.exitCode,
+						command: err.command,
+						args: err.args,
+						suggestion: 'Check file permissions and available disk space before retrying.',
+						cause: err,
+					}
+				);
+
+			}
+
+			throw err;
+
+		}
+
+	} finally {
+
+		if ( tmp ) {
+
+			try {
+
+				fs.rmSync( tmp, { recursive: true, force: true } );
+
+			} catch ( cleanupErr ) {
+
+				logDebug( `Unable to remove temp directory ${tmp}: ${cleanupErr?.message || cleanupErr}` );
+
+			}
+
+		}
+
+	}
+
+	// 4) Write .env.local and .gitignore entries
+	await fsp.writeFile( path.join( targetDir, '.env.local' ),
+		`THREE_BLOCKS_SECRET_KEY=${license}\nTHREE_BLOCKS_CHANNEL=${channel}\n`, { mode: 0o600 } ).catch( () => {} );
+	const giPath = path.join( targetDir, '.gitignore' );
+	let gi = '';
+	try {
+
+		gi = await fsp.readFile( giPath, 'utf8' );
+
+	} catch {}
+
+	for ( const line of [ '.env.local', '.npmrc' ] ) {
+
+		if ( ! gi.includes( line ) ) gi += ( gi.endsWith( '\n' ) || gi === '' ? '' : '\n' ) + line + '\n';
+
+	}
+
+	await fsp.writeFile( giPath, gi );
+
+	// 5) First install — the starter already has:
+	//    "preinstall": "npx -y three-blocks-login --mode project --scope @three-blocks"
+	//    so it will mint a fresh token and write a project .npmrc.
+	try {
+
+		const pkgPath = path.join( targetDir, 'package.json' );
+		const pkgRaw = await fsp.readFile( pkgPath, 'utf8' );
+		const pkg = JSON.parse( pkgRaw );
+		pkg.scripts = pkg.scripts || {};
+		if ( ! pkg.scripts.preinstall ) {
+
+			pkg.scripts.preinstall = `npx -y ${LOGIN_CLI}@latest --mode project --scope ${SCOPE} --channel ${channel}`;
+
+		}
+
+		await fsp.writeFile( pkgPath, JSON.stringify( pkg, null, 2 ) );
+		logSuccess( 'Added preinstall to generated package.json to refresh token on installs.' );
+
+	} catch ( e ) {
+
+		logWarn( `Warning: could not add preinstall to package.json: ${e?.message || String( e )}` );
+
+	}
+
+	logProgress( 'Installing dependencies (preinstall will refresh token) ...' );
+	const hasPnpm = spawnSync( 'pnpm', [ '-v' ], { stdio: 'ignore', env: cleanNpmEnv() } ).status === 0;
+	try {
+
+		run( hasPnpm ? 'pnpm' : 'npm', [ hasPnpm ? 'install' : 'ci' ], {
+			cwd: targetDir,
+			env: {
+				...process.env,
+				THREE_BLOCKS_SECRET_KEY: license,
+				THREE_BLOCKS_CHANNEL: channel,
+			},
+		} );
+
+	} catch ( err ) {
+
+		if ( err instanceof CliError ) {
+
+			throw new CliError(
+				'Dependency installation failed.',
+				{
+					exitCode: err.exitCode,
+					command: err.command,
+					args: err.args,
+					stdout: err.stdout,
+					stderr: err.stderr,
+					suggestion: 'Inspect the log above for npm/pnpm errors or retry with --debug for full output.',
+					cause: err,
+				}
+			);
+
+		}
+
+		throw err;
+
+	}
+
+	{
+
+		const coreSpec = `@three-blocks/core@${channel === 'stable' ? 'latest' : channel}`;
+		logProgress( `Installing ${coreSpec} ...` );
+		const addArgs = hasPnpm ? [ 'add', '--save-exact', coreSpec ] : [ 'install', '--save-exact', coreSpec ];
+		const r = spawnSync( hasPnpm ? 'pnpm' : 'npm', addArgs, {
+			stdio: 'inherit',
+			cwd: targetDir,
+			env: cleanNpmEnv( {
+				THREE_BLOCKS_SECRET_KEY: license,
+				THREE_BLOCKS_CHANNEL: channel,
+			} ),
+		} );
+		if ( r.status !== 0 ) {
+
+			logWarn( `Warning: could not install @three-blocks/core (exit ${r.status}).` );
+
+		}
+
+	}
+
+	console.log( '' );
+	logSuccess( `${appName} is ready.` );
+	console.log( '' );
+	logInfo( 'Next:' );
+	console.log( `  cd ${appName}` );
+	console.log( `  ${hasPnpm ? 'pnpm dev' : 'npm run dev'}` );
+	console.log( '' );
+	logInfo( 'Notes:' );
+	console.log( `  • Your license key is stored in .env.local (gitignored).` );
+	console.log( `  • ${SCOPE} packages are private; each install refreshes a short-lived token via preinstall.` );
+
 }
 
-main().catch((e) => {
-  logError(e?.stack || e?.message || String(e));
-  process.exit(1);
-});
+main().catch( ( err ) => {
+
+	if ( err instanceof CliError ) {
+
+		logError( err.message );
+		const detail = ( err.stderr || err.stdout || '' ).trim();
+		if ( detail ) {
+
+			const lines = detail.split( /\r?\n/ );
+			for ( const line of lines ) console.error( dim( `    ${line}` ) );
+
+		}
+
+		if ( err.suggestion ) logInfo( dim( `Hint: ${err.suggestion}` ) );
+		if ( DEBUG && err.cause && err.cause !== err && err.cause?.stack ) {
+
+			console.error( dim( err.cause.stack ) );
+
+		}
+
+		process.exit( err.exitCode ?? 1 );
+
+	}
+
+	const fallback = err?.stack || err?.message || String( err );
+	logError( fallback );
+	process.exit( 1 );
+
+} );