@expokit/cli 0.3.0 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@
 ![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
@@ -29,16 +29,20 @@ 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.karandev.in; your token is stored readable only by you, sent only to that site and never through a redirect.
-- **Runs one command:** `npx expo install` for the packages a component needs.
+  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).
 

package/bin/expo-kit.js

@@ -14,20 +14,28 @@ 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));
@@ -40,6 +48,8 @@ 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',
@@ -179,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,
   };
@@ -204,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,
   };
@@ -357,12 +375,9 @@ 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',
@@ -374,6 +389,26 @@ 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(
@@ -388,6 +423,11 @@ async function apiGet(pathname, token) {
   } 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 };
 }
 
@@ -395,12 +435,33 @@ 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 (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) {
@@ -411,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 \`${RUN} 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.`);
@@ -516,13 +577,37 @@ function promptSecret(question) {
   });
 }
 
+/**
+ * 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 (it won't be shown).`);
-    if (!process.stdin.isTTY) fail(`No token given. Use: ${RUN} login --token <token>`);
-    token = await promptSecret('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.');
@@ -531,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)
+    );
   }
 }
 
@@ -557,10 +645,10 @@ async function cmdWhoami() {
   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 = []) {
@@ -726,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);
@@ -751,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',
   });
@@ -762,6 +856,17 @@ function runExpoInstall(projectRoot, packages, dryRun) {
   return true;
 }
 
+/** 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}$/;
 
@@ -778,6 +883,7 @@ function createExpoApp(cwd, dir, flags) {
   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',
   });
@@ -808,7 +914,7 @@ function cmdInit(cwd, flags, dir) {
 
   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,
   };
@@ -918,6 +1024,7 @@ async function cmdAdd(args, cwd) {
       ensureExpoRouterMain(projectRoot, true);
     }
     runExpoInstall(projectRoot, meta.dependencies ?? [], true);
+    if (resolved !== 'liquidglass-tab') printRunHint(meta.dependencies);
     return;
   }
 
@@ -956,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);
   }
 }
 
@@ -1070,6 +1176,11 @@ 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)) {
@@ -1178,7 +1289,7 @@ Usage:
   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
@@ -1199,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}).
 

package/bin/lib.mjs

@@ -2,6 +2,8 @@
  * Pure helpers for the expo-kit CLI (no I/O, no dependencies) — kept separate so they can be unit-tested.
  */
 
+import path from 'node:path';
+
 /** Thrown for user-facing errors; the CLI entry point prints `message` and exits 1. */
 export class CliError extends Error {}
 
@@ -269,6 +271,27 @@ export function isValidItemName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9-]{0,99}$/.test(name);
 }
 
+/**
+ * Tab names from the user's tabs.ts become route files in app/(tabs)/: letters, digits and route punctuation
+ * (`-_.()[]`) only, so a name can never be a path like `../../x`.
+ */
+export function isSafeTabName(name) {
+  return typeof name === 'string' && name.length <= 100 && /^[A-Za-z0-9_.()[\]-]+$/.test(name) && !/^\.+$/.test(name);
+}
+
+// ---------------------------------------------------------------------------
+// Project paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether `rel` (a components.json `paths` value) stays inside `root` once joined to it the way the CLI
+ * writes files: `../x` escapes, while `/src/lib` is re-rooted by path.join and stays inside.
+ */
+export function isInsideDir(root, rel) {
+  const r = path.relative(root, path.join(root, rel));
+  return r === '' || (r !== '..' && !r.startsWith(`..${path.sep}`) && !path.isAbsolute(r));
+}
+
 /**
  * npm package name, optionally with a simple version (`@1.2.3`, `@~14.0.0`, `@^2`). It reaches
  * `npx expo install` through a shell on Windows, so no `< > | =` or spaces — ranges like `>=1` are out.
@@ -288,6 +311,46 @@ export function kitVersion(text) {
   return /export function KitProvider\b/.test(text) ? 1 : null;
 }
 
+/**
+ * Packages a registry item may depend on that work in the Expo Go app (SDK 58): native modules Expo Go
+ * ships, plus pure-JS packages. Anything else needs a development build (`npx expo run:ios|android`).
+ * Keep in sync with the Expo Go module list when the SDK moves.
+ */
+export const EXPO_GO_PACKAGES = new Set([
+  '@expo/vector-icons',
+  '@shopify/react-native-skia',
+  'expo-blur',
+  'expo-charts',
+  'expo-glass-effect',
+  'expo-haptics',
+  'expo-router',
+  'expo-splash-screen',
+  'react-native-gesture-handler',
+  'react-native-reanimated',
+  'react-native-safe-area-context',
+  'react-native-screens',
+  'react-native-svg',
+  'react-native-worklets',
+]);
+
+/** Which of `deps` keep an item out of Expo Go (bare names; `pkg@1.2` is read as `pkg`). Empty: runs in Expo Go. */
+export function needsDevBuild(deps) {
+  return (deps ?? [])
+    .map((spec) => spec.replace(/^(@?[^@]+)@.*$/, '$1'))
+    .filter((name) => !EXPO_GO_PACKAGES.has(name));
+}
+
+/**
+ * The component a file is named for: the PascalCase export matching one of `names` ("Grain Gradient" or
+ * "grain-gradient" → GrainGradient), else the first PascalCase export (never a CONSTANT).
+ */
+export function pickMainExport(source, names = []) {
+  const exports = [...source.matchAll(/export (?:function|const) ([A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*)\b/g)].map((m) => m[1]);
+  const pascal = (s) => String(s ?? '').split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+  const wanted = names.map(pascal).map((n) => n.toLowerCase());
+  return exports.find((e) => wanted.includes(e.toLowerCase())) ?? exports[0] ?? null;
+}
+
 /** Union of dependency lists, order preserved. */
 export function mergeDependencies(...lists) {
   const out = [];
@@ -301,7 +364,7 @@ export function mergeDependencies(...lists) {
 // Site URL + token guard
 // ---------------------------------------------------------------------------
 
-export const DEFAULT_SITE_URL = 'https://expokit.karandev.in';
+export const DEFAULT_SITE_URL = 'https://expokit.in';
 
 export function isLoopbackHost(hostname) {
   return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
@@ -341,3 +404,49 @@ export function canSendToken({ siteUrl, credsUrl, fromEnv = false, defaultUrl =
   if (fromEnv) return isLoopbackHost(new URL(siteUrl).hostname);
   return Boolean(credsUrl) && target === originOf(credsUrl);
 }
+
+/**
+ * `env` without EXPO_KIT_TOKEN, for child processes: `npx expo install` runs third-party install scripts,
+ * and none of them needs the Pro token. Case-insensitive, as Windows env names are.
+ */
+export function envWithoutToken(env) {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => key.toUpperCase() !== 'EXPO_KIT_TOKEN'));
+}
+
+// ---------------------------------------------------------------------------
+// 429 / 503: wait once, then give up
+// ---------------------------------------------------------------------------
+
+/** The longest the CLI waits before its one retry of a 429 / 503. */
+export const RETRY_MAX_WAIT_MS = 10_000;
+
+/** A Retry-After header (delta-seconds or an HTTP date) in whole seconds from `now`; null when missing or unreadable. */
+export function parseRetryAfter(value, now = Date.now()) {
+  if (value === null || value === undefined) return null;
+  const text = String(value).trim();
+  if (/^\d+$/.test(text)) return Number(text);
+  if (!/[A-Za-z]/.test(text)) return null; // an HTTP date always names its day / month
+  const at = Date.parse(text);
+  return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - now) / 1000));
+}
+
+/**
+ * Milliseconds to wait before retrying a 429 / 503 once: what the server asked (3 s when it didn't say).
+ * null when it asked for longer than RETRY_MAX_WAIT_MS: retrying sooner than that just earns another 429 / 503.
+ */
+export function retryDelayMs(retryAfter, now = Date.now()) {
+  const secs = parseRetryAfter(retryAfter, now);
+  if (secs === null) return 3000;
+  if (secs * 1000 > RETRY_MAX_WAIT_MS) return null;
+  return secs * 1000;
+}
+
+/** "in 30 s" / "in 5 min" / "in about 2 h" for a "try again …" message; "in a minute" when the server didn't say. */
+export function retryHint(retryAfter, now = Date.now()) {
+  const secs = parseRetryAfter(retryAfter, now);
+  if (secs === null) return 'in a minute';
+  if (secs < 90) return `in ${Math.max(1, secs)} s`;
+  if (secs < 90 * 60) return `in ${Math.round(secs / 60)} min`;
+  if (secs < 48 * 3600) return `in about ${Math.round(secs / 3600)} h`;
+  return 'later';
+}

package/bin/mcp.mjs

@@ -10,6 +10,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { needsDevBuild } from './lib.mjs';
+
 /** Newest first; we answer with the client's version when we know it, else our newest. */
 export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 
@@ -21,7 +23,7 @@ Items are copied into the user's app as source files by the expo-kit CLI — the
 Workflow: search_items or list_items → view_item (props, import line, examples) → get_add_command, then run that command in the app's root folder.
 The CLI creates components.json, adds the @/* tsconfig alias, copies files under src/ (or the root app layout) and installs npm deps with \`npx expo install\`.
 Import components from '@/components/...' and wrap the app in <KitProvider> from '@/lib/kit' (added with the first item).
-Pro items need an ExpoKit Pro plan: the user runs \`npx ${PACKAGE}@latest login\` once (token from https://expokit.karandev.in/account). Never ask the user to paste a token into chat.`;
+Pro items need an ExpoKit Pro plan: the user runs \`npx ${PACKAGE}@latest login\` once (token from https://expokit.in/account). Never ask the user to paste a token into chat.`;
 
 // ---------------------------------------------------------------------------
 // Registry access (bundled JSON)
@@ -187,6 +189,8 @@ function viewItem(catalog, registryDir, { name, include_source: includeSource =
   if (imp) out.push(`Import: \`${imp}\``);
   if (doc?.files?.length) out.push(`Files it adds: ${doc.files.join(', ')}`);
   if (it.dependencies.length) out.push(`npm deps (installed by the CLI): ${it.dependencies.join(', ')}`);
+  const native = needsDevBuild(it.dependencies);
+  out.push(native.length ? `Runs in Expo Go: no, needs a development build (${native.join(', ')})` : 'Runs in Expo Go: yes');
   if (it.registryDependencies.length) out.push(`Also adds: ${it.registryDependencies.join(', ')}`);
 
   if (doc?.props?.length) {
@@ -206,7 +210,7 @@ function viewItem(catalog, registryDir, { name, include_source: includeSource =
     out.push('', '## Examples');
     for (const ex of doc.examples) out.push('', `### ${ex.title}`, '', '```tsx', ex.code.trimEnd(), '```');
   } else if (it.tier === 'pro') {
-    out.push('', 'Usage examples and source for Pro items are on https://expokit.karandev.in after signing in, and in the files the add command copies.');
+    out.push('', 'Usage examples and source for Pro items are on https://expokit.in after signing in, and in the files the add command copies.');
   }
 
   if (includeSource) {
@@ -240,7 +244,7 @@ function getAddCommand(catalog, { names }) {
   ];
   if (pro.length)
     lines.push(
-      `- PRO: ${pro.join(', ')} ${pro.length === 1 ? 'needs' : 'need'} an ExpoKit Pro plan. If the command reports "not logged in", ask the user to run \`npx ${PACKAGE}@latest login\` themselves (token from https://expokit.karandev.in/account). Never ask for the token in chat.`
+      `- PRO: ${pro.join(', ')} ${pro.length === 1 ? 'needs' : 'need'} an ExpoKit Pro plan. If the command reports "not logged in", ask the user to run \`npx ${PACKAGE}@latest login\` themselves (token from https://expokit.in/account). Never ask for the token in chat.`
     );
   return lines.join('\n');
 }
@@ -265,15 +269,19 @@ export function callTool(catalog, registryDir, name, args = {}) {
 // ---------------------------------------------------------------------------
 
 const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
 
 /** One incoming JSON-RPC message → the response object, or null for notifications. */
 export function handleMessage(msg, ctx) {
-  if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
-    return msg && 'id' in msg ? rpcError(msg.id ?? null, -32600, 'Invalid request') : null;
+  if (!isObject(msg) || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+    // A stray `5`, "abc" or nested array has no id to answer; an object with one gets an error back.
+    return isObject(msg) && 'id' in msg ? rpcError(msg.id ?? null, -32600, 'Invalid request') : null;
   }
   const isRequest = 'id' in msg && msg.id !== null;
   if (!isRequest) return null; // notifications/initialized, notifications/cancelled, …
-  const { id, method, params = {} } = msg;
+  const { id, method } = msg;
+  // `params: null` skips a destructuring default, and params.name would then throw.
+  const params = isObject(msg.params) ? msg.params : {};
   const ok = (result) => ({ jsonrpc: '2.0', id, result });
 
   switch (method) {
@@ -313,6 +321,30 @@ export function handleMessage(msg, ctx) {
   }
 }
 
+/**
+ * One stdin line → what to write back: a reply, an array of replies for a batch, or null. Never throws —
+ * it runs inside the stdin listener, where one bad line would otherwise kill the server for the session.
+ */
+export function handleLine(line, ctx) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return rpcError(null, -32700, 'Parse error');
+  }
+  const reply = (m) => {
+    try {
+      return handleMessage(m, ctx);
+    } catch {
+      return isObject(m) && 'id' in m && m.id !== null ? rpcError(m.id, -32603, 'Internal error') : null;
+    }
+  };
+  if (!Array.isArray(msg)) return reply(msg);
+  // Batches came and went in 2025-03-26; answer them anyway.
+  const replies = msg.map(reply).filter(Boolean);
+  return replies.length ? replies : null;
+}
+
 /** Serves MCP on stdin/stdout until stdin closes. */
 export function startMcpServer({ registryDir, version, aliases }) {
   const ctx = { registryDir, version, catalog: loadCatalog(registryDir, aliases) };
@@ -326,18 +358,8 @@ export function startMcpServer({ registryDir, version, aliases }) {
       const line = buffer.slice(0, nl).trim();
       buffer = buffer.slice(nl + 1);
       if (!line) continue;
-      let msg;
-      try {
-        msg = JSON.parse(line);
-      } catch {
-        send(rpcError(null, -32700, 'Parse error'));
-        continue;
-      }
-      // Batches came and went in 2025-03-26; answer them anyway.
-      const replies = (Array.isArray(msg) ? msg : [msg]).map((m) => handleMessage(m, ctx)).filter(Boolean);
-      if (Array.isArray(msg)) {
-        if (replies.length) send(replies);
-      } else if (replies[0]) send(replies[0]);
+      const reply = handleLine(line, ctx);
+      if (reply) send(reply);
     }
   });
   process.stdin.on('end', () => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expokit/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "shadcn-style CLI for Expo — add native UI blocks and components to your app",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://expokit.karandev.in",
+  "homepage": "https://expokit.in",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Anshkaran7/expokit.git",