@expokit/cli 0.2.0 → 0.4.0

package/README.md

@@ -1,9 +1,12 @@
 # @expokit/cli
 
 [![npm](https://img.shields.io/npm/v/@expokit/cli.svg)](https://www.npmjs.com/package/@expokit/cli)
+[![CI](https://github.com/Anshkaran7/expokit/actions/workflows/ci.yml/badge.svg)](https://github.com/Anshkaran7/expokit/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Anshkaran7/expokit/badge)](https://scorecard.dev/viewer/?uri=github.com/Anshkaran7/expokit)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
-The CLI for **[ExpoKit](https://expokit.karandev.in)** — animated UI components for Expo and React Native. It copies
+The CLI for **[ExpoKit](https://expokit.in)** — animated UI components for Expo and React Native. It copies
 the component source into your app (like shadcn/ui), so you own the code.
 
 ## Usage
@@ -26,7 +29,22 @@ See every component: `npx @expokit/cli@latest add --list`
 ## Docs
 
 Everything else — live previews, props, installation, theming, Pro, AI / MCP setup and help — is on
-**[expokit.karandev.in](https://expokit.karandev.in/docs)**.
+**[expokit.in](https://expokit.in/docs)**.
+
+## Security
+
+- **No dependencies, no install scripts, no telemetry.**
+- **Writes only inside your app** — `components.json`, the `@/*` alias in `tsconfig.json` and the component files.
+  `--dry-run` shows every change first; `add` never overwrites a file you changed unless you pass `--force`.
+  `paths` in `components.json` that point outside the app are refused. Symlinks inside the app are followed, not
+  checked, so a cloned repo that symlinks a folder elsewhere can still send writes there.
+- **Free components need no network** — they ship inside this package. Pro components are downloaded over HTTPS from
+  expokit.in; your token is stored readable only by you, sent only to that site and never through a redirect.
+  In scripts, pipe it to `login` or set `EXPO_KIT_TOKEN` (`--token` leaves it in your shell history).
+- **Runs one command:** `npx expo install` for the packages a component needs — without `EXPO_KIT_TOKEN` in its
+  environment, so install scripts never see your token.
+
+Report a vulnerability privately: [SECURITY.md](https://github.com/Anshkaran7/expokit/blob/main/SECURITY.md).
 
 ## License
 

package/bin/expo-kit.js

@@ -13,20 +13,29 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
+import { Writable } from 'node:stream';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import {
   CliError,
   DEFAULT_SITE_URL,
   addTsconfigPathAlias,
   canSendToken,
+  envWithoutToken,
   hasJsoncExtras,
+  isInsideDir,
   isSafePackageSpec,
+  isSafeTabName,
   isValidItemName,
   kitVersion,
   mergeDependencies,
   parseJsonc,
   parseSiteUrl,
+  retryDelayMs,
+  retryHint,
   tabComponentName,
+  needsDevBuild,
+  pickMainExport,
 } from './lib.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -36,7 +45,11 @@ const REGISTRY_DIR = path.join(PACKAGE_ROOT, 'registry');
 /** Website that serves Pro items (GET /api/registry/<name>) and issues CLI tokens (/account). */
 const SITE_URL = (process.env.EXPO_KIT_URL || DEFAULT_SITE_URL).replace(/\/+$/, '');
 const CREDENTIALS_DIR = path.join(os.homedir(), '.expo-kit');
+/** How users run the CLI. Bare `expo-kit` only works once installed, and `npx expo-kit` would fetch an unrelated npm package. */
+const RUN = 'npx @expokit/cli@latest';
 const CREDENTIALS_PATH = path.join(CREDENTIALS_DIR, 'credentials.json');
+/** Env for `npx expo install` / create-expo-app: they run third-party install scripts that never need the Pro token. */
+const childEnv = envWithoutToken(process.env);
 
 const DEFAULT_ALIASES = {
   components: '@/components',
@@ -176,7 +189,7 @@ function detectProjectLayout(projectRoot) {
 function buildDefaultConfig(projectRoot) {
   const { paths } = detectProjectLayout(projectRoot);
   return {
-    $schema: 'https://expokit.karandev.in/schema.json',
+    $schema: 'https://expokit.in/schema.json',
     aliases: { ...DEFAULT_ALIASES },
     paths,
   };
@@ -201,11 +214,19 @@ function loadConfig(projectRoot) {
     return { ...defaults, configPath };
   }
   const user = readJsonFile(configPath, 'components.json');
+  const paths = { ...defaults.paths, ...user.paths };
+  // Every write goes to path.join(projectRoot, paths.*): a "../" from a cloned repo would land outside the app.
+  for (const [key, value] of Object.entries(paths)) {
+    if (value === null || value === undefined) continue; // falls back to the default folder
+    if (typeof value !== 'string' || !isInsideDir(projectRoot, value)) {
+      throw new CliError(`components.json paths.${key} (${JSON.stringify(value)}) must be a folder inside the project. Fix it and re-run.`);
+    }
+  }
   return {
     ...defaults,
     ...user,
     aliases: { ...defaults.aliases, ...user.aliases },
-    paths: { ...defaults.paths, ...user.paths },
+    paths,
     installed: { ...user.installed },
     configPath,
   };
@@ -295,7 +316,7 @@ async function loadRegistryItem(name) {
   const resolved = resolveRegistryName(name);
   const meta = isValidItemName(resolved) ? readMeta(resolved) : null;
   if (!meta) {
-    if (!isValidItemName(resolved)) fail(`Unknown item "${name}". Run: expo-kit add --list`);
+    if (!isValidItemName(resolved)) fail(`Unknown item "${name}". Run: ${RUN} add --list`);
     // Not in this package's registry — it may be newer than this CLI. Ask the site before giving up.
     const remoteMeta = { name: resolved, title: resolved, tier: 'pro', dependencies: [], unknownLocally: true };
     return stageRemoteItem(remoteMeta, resolved);
@@ -317,7 +338,7 @@ function listRegistry() {
     console.log(`  • ${meta.name.padEnd(18)} ${tag}${meta.title}`);
   }
   console.log('');
-  if (pro) log(`PRO items need an ExpoKit Pro plan — run \`expo-kit login\` (tokens: ${SITE_URL}/account).\n`);
+  if (pro) log(`PRO items need an ExpoKit Pro plan — run \`${RUN} login\` (tokens: ${SITE_URL}/account).\n`);
 }
 
 // ---------------------------------------------------------------------------
@@ -342,9 +363,9 @@ function assertTokenTarget(creds) {
   const target = new URL(SITE_URL).origin;
   throw new CliError(
     creds.fromEnv
-      ? `Refusing to send EXPO_KIT_TOKEN to ${target} (only ${DEFAULT_SITE_URL} or localhost receive it). Unset EXPO_KIT_URL, or run \`expo-kit login\` against that site.`
+      ? `Refusing to send EXPO_KIT_TOKEN to ${target} (only ${DEFAULT_SITE_URL} or localhost receive it). Unset EXPO_KIT_URL, or run \`${RUN} login\` against that site.`
       : `Your saved token was created for ${creds.url ?? DEFAULT_SITE_URL}, so it won't be sent to ${target}. ` +
-        `Unset EXPO_KIT_URL, or run \`expo-kit login\` with EXPO_KIT_URL=${target} to save a token for that site.`
+        `Unset EXPO_KIT_URL, or run \`${RUN} login\` with EXPO_KIT_URL=${target} to save a token for that site.`
   );
 }
 
@@ -354,13 +375,12 @@ function writeCredentials(data) {
   fs.chmodSync(CREDENTIALS_PATH, 0o600); // also when the file already existed
 }
 
-async function apiGet(pathname, token) {
-  parseSiteUrl(SITE_URL); // https only (http just for localhost) — throws CliError
-  const url = `${SITE_URL}${pathname}`;
-  let res;
+async function siteFetch(url, token) {
   try {
-    res = await fetch(url, {
+    return await fetch(url, {
       headers: { Accept: 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      // A request that carries the token never follows a redirect: the token goes to SITE_URL's origin only.
+      redirect: token ? 'manual' : 'follow',
       signal: AbortSignal.timeout(20000),
     });
   } catch (e) {
@@ -369,12 +389,45 @@ async function apiGet(pathname, token) {
         'Check your connection (or EXPO_KIT_URL) and try again.'
     );
   }
+}
+
+/** Rate limited (429) or briefly unavailable (503): worth one polite retry. */
+const BUSY_STATUSES = new Set([429, 503]);
+
+async function apiGet(pathname, token) {
+  parseSiteUrl(SITE_URL); // https only (http just for localhost) — throws CliError
+  const url = `${SITE_URL}${pathname}`;
+  let res = await siteFetch(url, token);
+  if (BUSY_STATUSES.has(res.status)) {
+    // Wait what the server asks (plus jitter so a crowd of CLIs doesn't come back in lockstep), then try once more.
+    // When it asks for more than 10 s, don't knock early: skip the retry and just say when to try again.
+    const wait = retryDelayMs(res.headers.get('retry-after'));
+    if (wait !== null) {
+      await res.arrayBuffer().catch(() => {});
+      log(`${new URL(SITE_URL).host} is busy (HTTP ${res.status}) — trying again in ${Math.max(1, Math.ceil(wait / 1000))} s…`);
+      await sleep(wait + Math.floor(Math.random() * 500));
+      res = await siteFetch(url, token);
+    }
+  }
+  if (token && res.status >= 300 && res.status < 400) {
+    const location = res.headers.get('location');
+    fail(
+      `${SITE_URL} answered with a redirect (HTTP ${res.status}${location ? ` to ${location}` : ''}). ` +
+        `Your token is only sent to ${new URL(SITE_URL).origin} directly, so nothing was sent on. ` +
+        'Check EXPO_KIT_URL, or update the CLI: npx @expokit/cli@latest'
+    );
+  }
   let body = null;
   try {
     body = await res.json();
   } catch {
     // non-JSON (proxy error page, …)
   }
+  if (BUSY_STATUSES.has(res.status)) {
+    const why = res.status === 429 ? 'is limiting requests (HTTP 429).' : "is temporarily unavailable (HTTP 503) — this isn't a problem with your token.";
+    const hint = typeof body?.message === 'string' && body.message ? body.message : `Try again ${retryHint(res.headers.get('retry-after'))}.`;
+    fail(`${SITE_URL} ${why} ${hint}`);
+  }
   return { status: res.status, ok: res.ok, body };
 }
 
@@ -382,13 +435,34 @@ function failServerError(status, what) {
   fail(`Server error from ${SITE_URL} (HTTP ${status}) while ${what}. This isn't a problem with your token — try again in a moment.`);
 }
 
-/** Downloads one Pro item (own files only). Exits with a clear message on 401 / 403 / 5xx. */
+/** Pro items already downloaded in this run, so `add a b c` and `update --force` fetch a shared dep (e.g. glass) once. */
+const remoteItemCache = new Map();
+
+/** The 401 message for a saved or given token: expired (the site says `token_expired`) or invalid / revoked. */
+function rejectedToken(body, which) {
+  return body?.error === 'token_expired'
+    ? `${which} has expired. Create a new one at ${SITE_URL}/account and run \`${RUN} login\`.`
+    : `${which} is invalid or was revoked. Create a new one at ${SITE_URL}/account and run \`${RUN} login\`.`;
+}
+
+/** " · token expires Jan 5, 2027" when the site sent an expiry, else "". */
+function expiryNote(body) {
+  const at = body?.expiresAt ? new Date(body.expiresAt) : null;
+  if (!at || Number.isNaN(at.getTime())) return '';
+  return ` · token expires ${at.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' })}`;
+}
+
+/** Downloads one Pro item (own files only). Exits with a clear message on 401 / 403 / 429 / 5xx. */
 async function fetchRemoteItem(name, { unknownLocally = false } = {}) {
+  if (remoteItemCache.has(name)) return remoteItemCache.get(name);
   const creds = readCredentials();
   assertTokenTarget(creds);
   const { status, ok, body } = await apiGet(`/api/registry/${encodeURIComponent(name)}`, creds?.token);
-  if (ok && body && Array.isArray(body.files)) return body;
-  if (status === 404 && unknownLocally) fail(`Unknown item "${name}". Run: expo-kit add --list`);
+  if (ok && body && Array.isArray(body.files)) {
+    remoteItemCache.set(name, body);
+    return body;
+  }
+  if (status === 404 && unknownLocally) fail(`Unknown item "${name}". Run: ${RUN} add --list`);
   if (status >= 500) failServerError(status, `downloading "${name}"`);
   if (status === 401 && !creds) {
     fail(
@@ -398,7 +472,7 @@ async function fetchRemoteItem(name, { unknownLocally = false } = {}) {
     );
   }
   if (status === 401) {
-    fail(`Your token (${creds.source}) is invalid or was revoked. Create a new one at ${SITE_URL}/account and run \`expo-kit login\`.`);
+    fail(rejectedToken(body, `Your token (${creds.source})`));
   }
   if (status === 403) {
     fail(`"${name}" needs ExpoKit Pro, and your account doesn't have it yet. Upgrade at ${SITE_URL}/pricing.`);
@@ -484,23 +558,56 @@ async function stageRemoteItem(meta, resolved) {
   return { meta: { ...meta, title, dependencies, sharedFiles: [...shared] }, filesRoot: tmp, resolved };
 }
 
-function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+/** Reads one line from the terminal without echoing it (for tokens), so it stays off the screen and out of scrollback. */
+function promptSecret(question) {
+  process.stdout.write(question);
+  const muted = new Writable({ write: (_chunk, _encoding, done) => done() });
+  const rl = readline.createInterface({ input: process.stdin, output: muted, terminal: true });
   return new Promise((resolve) => {
-    rl.question(question, (answer) => {
+    rl.on('SIGINT', () => {
       rl.close();
+      process.stdout.write('\n');
+      process.exit(130);
+    });
+    rl.question('', (answer) => {
+      rl.close();
+      process.stdout.write('\n');
       resolve(answer.trim());
     });
   });
 }
 
+/**
+ * First non-blank line of a non-TTY stdin (`printf %s "$TOKEN" | … login`, or typed into a console without a TTY):
+ * the token never lands in argv, shell history or `ps`.
+ */
+async function readTokenFromStdin() {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    data += chunk;
+    // Stop at the first non-blank line: a pipe left open (Git Bash/mintty, IDE consoles) never sends EOF after Enter.
+    if (/\S.*\n/.test(data)) break;
+    if (data.length > 4096) break; // a token is ~50 chars; don't slurp a whole file
+  }
+  return data.trim().split(/\r?\n/)[0].trim();
+}
+
 async function cmdLogin(args) {
   const i = args.findIndex((a) => a === '--token' || a.startsWith('--token='));
   let token = i === -1 ? '' : args[i].includes('=') ? args[i].slice('--token='.length) : args[i + 1] ?? '';
+  if (i !== -1) warn('--token leaves the token in your shell history. Prefer the prompt, piping it in, or EXPO_KIT_TOKEN.');
   if (!token) {
-    log(`Create a CLI token at ${SITE_URL}/account (signed in), then paste it here.`);
-    if (!process.stdin.isTTY) fail('No token given. Use: expo-kit login --token <token>');
-    token = await prompt('Token: ');
+    if (process.stdin.isTTY) {
+      log(`Create a CLI token at ${SITE_URL}/account (signed in), then paste it here (it won't be shown).`);
+      token = await promptSecret('Token: ');
+    } else {
+      log(`Paste your token from ${SITE_URL}/account and press Enter (or pipe it in)…`);
+      token = await readTokenFromStdin();
+      if (!token) {
+        fail(`No token given. Pipe it in (printf %s "$TOKEN" | ${RUN} login) or set EXPO_KIT_TOKEN. Tokens: ${SITE_URL}/account`);
+      }
+    }
   }
   token = token.trim();
   if (!token) fail('No token given.');
@@ -509,14 +616,17 @@ async function cmdLogin(args) {
   log(`Verifying the token with ${site.host} — it will only be sent to ${site.origin}.`);
   if (site.origin !== new URL(DEFAULT_SITE_URL).origin) warn(`${site.origin} is not the default site (EXPO_KIT_URL is set).`);
   const { status, ok, body } = await apiGet('/api/cli/whoami', token);
-  if (status === 401) fail(`That token isn't valid (or was revoked). Create a new one at ${SITE_URL}/account.`);
+  if (status === 401) fail(rejectedToken(body, 'That token'));
   if (status >= 500) failServerError(status, 'verifying the token');
   if (!ok) fail(`Couldn't verify the token (HTTP ${status}). Check your network and ${SITE_URL}, then try again.`);
 
   writeCredentials({ token, url: site.origin, savedAt: new Date().toISOString() });
   log(`Saved to ${CREDENTIALS_PATH} (readable only by you).`);
   if (ok && body) {
-    log(body.pro ? `Logged in — Pro is unlocked (${body.plan} plan).` : `Logged in on the ${body.plan} plan. Pro items need Pro: ${SITE_URL}/pricing`);
+    log(
+      (body.pro ? `Logged in — Pro is unlocked (${body.plan} plan).` : `Logged in on the ${body.plan} plan. Pro items need Pro: ${SITE_URL}/pricing`) +
+        expiryNote(body)
+    );
   }
 }
 
@@ -532,13 +642,13 @@ function cmdLogout() {
 
 async function cmdWhoami() {
   const creds = readCredentials();
-  if (!creds) fail(`Not logged in. Run: expo-kit login (tokens: ${SITE_URL}/account)`);
+  if (!creds) fail(`Not logged in. Run: ${RUN} login (tokens: ${SITE_URL}/account)`);
   assertTokenTarget(creds);
   const { status, ok, body } = await apiGet('/api/cli/whoami', creds.token);
-  if (status === 401) fail(`Your token (${creds.source}) is invalid or was revoked. Create a new one at ${SITE_URL}/account.`);
+  if (status === 401) fail(rejectedToken(body, `Your token (${creds.source})`));
   if (status >= 500) failServerError(status, 'checking your token');
   if (!ok || !body) fail(`Couldn't check your token (HTTP ${status}).`);
-  log(`User ${body.userId} · ${body.plan} plan · Pro ${body.pro ? 'unlocked' : 'locked'} · ${SITE_URL}`);
+  log(`User ${body.userId} · ${body.plan} plan · Pro ${body.pro ? 'unlocked' : 'locked'}${expiryNote(body)} · ${SITE_URL}`);
 }
 
 function collectFiles(src, dest, files = []) {
@@ -704,6 +814,11 @@ function syncTabRoutes(projectRoot, config, options) {
   }
 
   for (const tabName of tabNames) {
+    // Names come from the user's tabs.ts and become file names: never let one be a path.
+    if (!isSafeTabName(tabName)) {
+      warn(`Skipping tab ${JSON.stringify(tabName)} in tabs.ts: route names may only use letters, numbers and - _ . ( ) [ ]`);
+      continue;
+    }
     const fileName = tabName === 'index' ? 'index.tsx' : `${tabName}.tsx`;
     const destPath = path.join(tabsDir, fileName);
     const rel = path.relative(projectRoot, destPath);
@@ -729,6 +844,7 @@ function runExpoInstall(projectRoot, packages, dryRun) {
   log(`Installing: ${packages.join(', ')}`);
   const result = spawnSync('npx', ['expo', 'install', ...packages], {
     cwd: projectRoot,
+    env: childEnv,
     stdio: 'inherit',
     shell: process.platform === 'win32',
   });
@@ -740,9 +856,55 @@ function runExpoInstall(projectRoot, packages, dryRun) {
   return true;
 }
 
-function cmdInit(cwd, flags) {
+/** After an add: can the item run in Expo Go, or does it need a development build? */
+function printRunHint(deps) {
+  const native = needsDevBuild(deps);
+  if (!native.length) {
+    log('Runs in Expo Go: npx expo start, then scan the QR code with your phone.');
+    return;
+  }
+  log(`Needs a development build (not in Expo Go): ${native.join(', ')}`);
+  console.log('  • Build and run it: npx expo run:ios  or  npx expo run:android');
+}
+
+/** Folder names `init <dir>` will create: no paths, no spaces, nothing a shell could misread. */
+const SAFE_APP_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** `init my-app`: a new Expo app (create-expo-app) in ./my-app, then the usual init inside it. */
+function createExpoApp(cwd, dir, flags) {
+  if (!SAFE_APP_DIR.test(dir)) fail(`"${dir}" is not a valid folder name (letters, numbers, ".", "_" and "-").`);
+  const target = path.join(cwd, dir);
+  if (fs.existsSync(target) && fs.readdirSync(target).length) fail(`./${dir} already exists and is not empty.`);
+  if (flags.dryRun) {
+    log(`Would run: npx create-expo-app@latest ${dir} --yes`);
+    log(`Would then set up ExpoKit in ./${dir}`);
+    return null;
+  }
+  log(`Creating a new Expo app in ./${dir}…`);
+  const result = spawnSync('npx', ['create-expo-app@latest', dir, '--yes'], {
+    cwd,
+    env: childEnv,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  if (result.status !== 0 || !fs.existsSync(path.join(target, 'package.json'))) {
+    fail(`create-expo-app failed. Create the app yourself (npx create-expo-app@latest ${dir}), then run ${RUN} init inside it.`);
+  }
+  return target;
+}
+
+function cmdInit(cwd, flags, dir) {
+  if (dir) {
+    // Already inside an Expo app: `init <dir>` still means "create a new one there".
+    const target = createExpoApp(cwd, dir, flags);
+    if (!target) return;
+    cmdInit(target, flags);
+    log('');
+    log(`Next: cd ${dir} && npx expo start — then scan the QR with Expo Go.`);
+    return;
+  }
   const projectRoot = findProjectRoot(cwd);
-  if (!projectRoot) fail('Not inside an Expo project (expo dependency not found).');
+  if (!projectRoot) fail(`Not inside an Expo project (expo dependency not found). Start a new app with: ${RUN} init my-app`);
 
   const configPath = path.join(projectRoot, 'components.json');
   if (fs.existsSync(configPath)) {
@@ -752,7 +914,7 @@ function cmdInit(cwd, flags) {
 
   const { paths, aliasTarget, layout } = detectProjectLayout(projectRoot);
   const config = {
-    $schema: 'https://expokit.karandev.in/schema.json',
+    $schema: 'https://expokit.in/schema.json',
     aliases: { ...DEFAULT_ALIASES },
     paths,
   };
@@ -777,7 +939,7 @@ function cmdInit(cwd, flags) {
   log(`Created components.json (${layout} layout)`);
 
   ensureExpoRouterMain(projectRoot, false);
-  log('Done. Add items with: npx @expokit/cli add <name>');
+  log(`Done. Add items with: ${RUN} add <name>`);
 }
 
 async function cmdAdd(args, cwd) {
@@ -862,6 +1024,7 @@ async function cmdAdd(args, cwd) {
       ensureExpoRouterMain(projectRoot, true);
     }
     runExpoInstall(projectRoot, meta.dependencies ?? [], true);
+    if (resolved !== 'liquidglass-tab') printRunHint(meta.dependencies);
     return;
   }
 
@@ -891,7 +1054,7 @@ async function cmdAdd(args, cwd) {
   if (resolved === 'liquidglass-tab') {
     log('Next steps:');
     console.log('  • Edit src/lib/tabs.ts — labels, icon presets, colors, screen text');
-    console.log('  • Run: npx expo-kit doctor');
+    console.log(`  • Run: ${RUN} doctor`);
     console.log('  • Build a dev client: npx expo run:ios (iOS 26 shows real Liquid Glass,');
     console.log('    iOS 18 and older, Android and web get the glass fallback bar)');
     console.log('  • After package updates: npx @expokit/cli@latest update');
@@ -900,10 +1063,9 @@ async function cmdAdd(args, cwd) {
       fs.existsSync(path.join(filesRoot, 'src', 'components', f, `${resolved}.tsx`))
     );
     const main = folder ? path.join(filesRoot, 'src', 'components', folder, `${resolved}.tsx`) : null;
-    const exported = main
-      ? fs.readFileSync(main, 'utf8').match(/export (?:function|const) ([A-Z]\w*)/)?.[1]
-      : null;
+    const exported = main ? pickMainExport(fs.readFileSync(main, 'utf8'), [meta.title, resolved]) : null;
     if (exported) log(`Import: import { ${exported} } from "@/components/${folder}/${resolved}";`);
+    printRunHint(meta.dependencies);
   }
 }
 
@@ -977,7 +1139,7 @@ function cmdDoctor(cwd) {
   log('Checking project…\n');
 
   if (!fs.existsSync(config.configPath)) {
-    warn('Missing components.json — run: expo-kit init');
+    warn(`Missing components.json — run: ${RUN} init`);
     issues += 1;
   } else {
     log('  ✓ components.json');
@@ -996,7 +1158,7 @@ function cmdDoctor(cwd) {
   const usesLiquidGlass = fs.existsSync(tabsPath) || config.installed?.['liquidglass-tab'];
   if (usesLiquidGlass) {
     if (!fs.existsSync(tabsPath)) {
-      warn('No src/lib/tabs.ts — run: expo-kit add liquidglass-tab');
+      warn(`No src/lib/tabs.ts — run: ${RUN} add liquidglass-tab`);
       issues += 1;
     } else {
       log('  ✓ src/lib/tabs.ts');
@@ -1014,11 +1176,16 @@ function cmdDoctor(cwd) {
       const tabsDir = path.join(projectRoot, config.paths.app ?? 'src/app', '(tabs)');
 
       for (const tabName of tabNames) {
+        if (!isSafeTabName(tabName)) {
+          warn(`Tab ${JSON.stringify(tabName)} in tabs.ts is not a valid route name (letters, numbers and - _ . ( ) [ ] only)`);
+          issues += 1;
+          continue;
+        }
         const fileName = tabName === 'index' ? 'index.tsx' : `${tabName}.tsx`;
         const routePath = path.join(tabsDir, fileName);
         if (!fs.existsSync(routePath)) {
           warn(`Missing route for tab "${tabName}": ${path.relative(projectRoot, routePath)}`);
-          console.log(`    Fix: add the file or run expo-kit add liquidglass-tab --force`);
+          console.log(`    Fix: add the file or run ${RUN} add liquidglass-tab --force`);
           issues += 1;
         } else {
           log(`  ✓ route ${path.relative(projectRoot, routePath)}`);
@@ -1073,7 +1240,7 @@ async function cmdMcp(args, cwd) {
   const i = args.findIndex((a) => a === '--client' || a.startsWith('--client='));
   const client = i < 0 ? undefined : args[i].includes('=') ? args[i].split('=')[1] : args[i + 1];
   const names = [...Object.keys(MCP_CLIENTS), 'codex'].join('|');
-  if (!client) fail(`Pick a client: expo-kit mcp init --client <${names}>`);
+  if (!client) fail(`Pick a client: ${RUN} mcp init --client <${names}>`);
 
   if (client === 'codex') {
     log('Codex reads MCP servers from ~/.codex/config.toml (shared by every project). Add:\n');
@@ -1117,18 +1284,19 @@ function printHelp() {
 expo-kit — copy-paste Expo UI (shadcn-style)
 
 Usage:
-  npx @expokit/cli@latest init
+  npx @expokit/cli@latest init [my-app] [--dry-run]
   npx @expokit/cli@latest add <name...> [--dry-run] [--force]
   npx @expokit/cli@latest update [name] [--dry-run] [--force]
   npx @expokit/cli@latest doctor
   npx @expokit/cli@latest add --list
-  npx @expokit/cli@latest login [--token <token>]
+  npx @expokit/cli@latest login
   npx @expokit/cli@latest logout
   npx @expokit/cli@latest whoami
   npx @expokit/cli@latest mcp
   npx @expokit/cli@latest mcp init --client <claude|cursor|vscode|codex>
 
 Examples:
+  npx @expokit/cli@latest init my-app        new Expo app with ExpoKit set up
   npx @expokit/cli@latest add liquidglass-tab --dry-run
   npx @expokit/cli@latest add liquidglass-tab --force
   npx @expokit/cli@latest update
@@ -1142,8 +1310,10 @@ auto-sync — run \`update\` after upgrading the package.
 files; tabs.ts kept). Other items: use \`add <name> --force\` to overwrite.
 
 Pro items (marked PRO in \`add --list\`): create a token at ${SITE_URL}/account,
-run \`login\`, then \`add\` them like any other item. Credentials live in
-~/.expo-kit/credentials.json (or set EXPO_KIT_TOKEN). EXPO_KIT_URL overrides the
+run \`login\` and paste it, then \`add\` them like any other item. In scripts, pipe
+it in (printf %s "$TOKEN" | npx @expokit/cli@latest login) or set EXPO_KIT_TOKEN;
+\`login --token <token>\` still works but leaves the token in your shell history.
+Credentials live in ~/.expo-kit/credentials.json. EXPO_KIT_URL overrides the
 site (https only; http just for localhost). A saved token is only sent to the site
 it was created for (or ${DEFAULT_SITE_URL}).
 
@@ -1159,10 +1329,15 @@ Config: components.json (created by init)
 async function main(command, rest) {
   switch (command) {
     case 'init': {
-      const { flags } = parseFlags(rest);
-      cmdInit(process.cwd(), flags);
+      const { flags, positional } = parseFlags(rest);
+      if (positional.length > 1) fail(`init takes one folder name: ${RUN} init my-app`);
+      cmdInit(process.cwd(), flags, positional[0]);
       break;
     }
+    case '--version':
+    case '-v':
+      console.log(getPackageVersion());
+      break;
     case 'add':
       await cmdAdd(rest, process.cwd());
       break;