create-twinbloc-app 0.1.1 → 0.1.3

package/README.md

@@ -1,14 +1,51 @@
 # Create Twinbloc App
 
-Create a React Native app from the Twinbloc starter template.
+Create a React Native app with the Twinbloc starter template. This CLI scaffolds a production-ready Expo SDK 54 project with Expo Router, TypeScript, native modules, and a curated set of defaults for state, API, UI, and localization.
 
-## Usage
+## What You Get
+
+- Expo SDK 54 project with Expo Router and typed routes
+- React Native 0.81 + React 19 setup
+- TypeScript-first structure with strict TS config
+- NativeWind + Tailwind utilities, themed UI primitives, and tokens
+- Zustand store examples with persisted auth state
+- TanStack Query with MMKV persistence
+- Axios API client with auth-aware helpers
+- i18next localization with English, Spanish, French, and Arabic samples
+- Reanimated-ready bottom sheet provider and gesture handler setup
+- Toasts, haptics, blur, image, and icon tooling prewired
+- Environment-driven app config for name, slug, scheme, bundle IDs
+
+## Requirements
+
+- Node.js 18+
+- npm, yarn, pnpm, or bun
+- Xcode for iOS (macOS) and/or Android Studio for Android
+
+## Quick Start (npm)
 
 ```bash
 npx create-twinbloc-app@latest MyApp
+cd MyApp
+npm run start
+```
+
+Then build and open a dev client:
+
+```bash
+npx expo run:ios
+npx expo run:android
+```
+
+## Using Other Package Managers
+
+```bash
+yarn create twinbloc-app MyApp
+pnpm create twinbloc-app MyApp
+bun create twinbloc-app MyApp
 ```
 
-## Options
+## CLI Options
 
 ```bash
 npx create-twinbloc-app@latest MyApp --example base
@@ -19,6 +56,87 @@ npx create-twinbloc-app@latest MyApp --pm pnpm
 npx create-twinbloc-app@latest MyApp --pm bun
 ```
 
-## Template
+### Example Variants
+
+Only the base template ships in this repo. Use:
+
+```bash
+npx create-twinbloc-app@latest MyApp --example base
+```
+
+## Running the App
+
+This starter includes native modules, so you should use a development build instead of Expo Go.
+
+```bash
+npm run start
+```
+
+Then run a dev client when you need native modules:
+
+```bash
+npx expo run:ios
+npx expo run:android
+```
+
+## Project Structure
+
+```
+MyApp/
+  app/              # Expo Router routes
+  assets/           # Images and icons
+  src/
+    api/            # Axios client and React Query helpers
+    components/     # UI components and providers
+    hooks/          # App hooks
+    lib/            # i18n, env, storage, utilities
+    store/          # Zustand stores
+    translations/   # i18n resource files
+  app.config.ts     # Env-driven Expo config
+  global.css        # NativeWind globals
+  package.json      # Scripts and dependencies
+  tsconfig.json     # TypeScript config
+```
+
+## Environment Configuration
+
+The template loads environment values from `.env.{APP_ENV}` and `.env` with `APP_ENV=development|staging|production`.
+
+Required by default:
+
+- `EXPO_PUBLIC_API_URL` for your API base URL
+
+Optional overrides:
+
+- `APP_NAME`, `APP_SLUG`, `APP_SCHEME`
+- `APP_BUNDLE_ID_DEVELOPMENT`, `APP_BUNDLE_ID_STAGING`, `APP_BUNDLE_ID_PRODUCTION`
+- `APP_PACKAGE_DEVELOPMENT`, `APP_PACKAGE_STAGING`, `APP_PACKAGE_PRODUCTION`
+
+Values are validated on startup. If you update `.env` files and still see errors, restart the dev server with `-c` to clear cache.
+
+## Scripts
+
+```bash
+npm run start        # Expo dev server
+npm run ios          # Build iOS dev client
+npm run android      # Build Android dev client
+npm run web          # Run web build
+npm run lint         # Lint project
+npm run test         # Jest tests
+npm run reset-project # Move starter to app-example and create a fresh app
+```
+
+## Template Details
+
+- Location: `template/react-native-starter`
+- Framework: Expo SDK 54 + Expo Router
+- Styling: NativeWind + Tailwind utilities
+- State: Zustand stores in `src/store`
+- Data: TanStack Query helpers in `src/api`
+- i18n: `src/lib/i18n` and `src/translations`
+
+## Troubleshooting
 
-The generated app is located in the `template/react-native-starter` directory of this package and uses Expo with Expo Router.
+- If install fails, retry with `--pm` to force a package manager.
+- If the folder is not empty, choose a new directory name.
+- If your app launches but native modules crash, rebuild the dev client.

package/bin/cli.js

@@ -5,6 +5,8 @@ import fs from "fs-extra";
 import { spawnSync } from "child_process";
 import chalk from "chalk";
 import { fileURLToPath } from "url";
+import readline from "readline";
+import { stdin as input, stdout as output } from "process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -64,6 +66,129 @@ const runInstall = (dir, pm) => {
   if (result.status !== 0) process.exit(result.status);
 };
 
+const brandPrimary = chalk.hex("#6CABDD");
+const brandDeep = chalk.hex("#1C2C5B");
+const rnBlue = chalk.hex("#61DAFB");
+const uiMuted = chalk.gray;
+const uiAccent = chalk.hex("#9FD7F2");
+const uiActive = chalk.hex("#88C6FF");
+const uiSelected = chalk.hex("#6EDC91");
+
+const printBanner = () => {
+  const lines = [
+    "████████╗██╗    ██╗██╗███╗   ██╗██████╗ ██╗      ██████╗  ██████╗",
+    "╚══██╔══╝██║    ██║██║████╗  ██║██╔══██╗██║     ██╔═══██╗██╔════╝",
+    "   ██║   ██║ █╗ ██║██║██╔██╗ ██║██████╔╝██║     ██║   ██║██║",
+    "   ██║   ██║███╗██║██║██║╚██╗██║██╔══██╗██║     ██║   ██║██║",
+    "   ██║   ╚███╔███╔╝██║██║ ╚████║██████╔╝███████╗╚██████╔╝╚██████╗",
+    "   ╚═╝    ╚══╝╚══╝ ╚═╝╚═╝  ╚═══╝╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝",
+  ];
+  lines.forEach((line, index) => {
+    const paint = index < 3 ? brandPrimary : brandDeep;
+    console.log(paint(line));
+  });
+  console.log(brandPrimary("React Native Starter"));
+  console.log(rnBlue("     ⚛  React Native  •  Expo + Router  •  TypeScript  •  Zustand"));
+  console.log("");
+};
+
+const agentDirectories = [
+  { key: "Antigravity", path: ".agents", label: ".agents/skills" },
+  { key: "agent", path: ".agent", label: ".agent/skills" },
+  { key: "claude", path: ".claude", label: ".claude/skills" },
+  { key: "codex", path: ".codex", label: ".codex/skills" },
+  { key: "cursor", path: ".cursor", label: ".cursor/skills" },
+  { key: "github", path: ".github", label: ".github/skills" },
+  { key: "kilocode", path: ".kilocode", label: ".kilocode/skills" },
+  { key: "opencode", path: ".opencode", label: ".opencode/skills" },
+  { key: "trae", path: ".trae", label: ".trae" },
+  { key: "vscode", path: ".vscode", label: ".vscode" },
+  { key: "windsurf", path: ".windsurf", label: ".windsurf" },
+];
+
+const getExistingAgentKeys = async (rootDir) => {
+  const existing = new Set();
+  for (const dir of agentDirectories) {
+    if (await fs.pathExists(path.join(rootDir, dir.path))) {
+      existing.add(dir.key);
+    }
+  }
+  return existing;
+};
+
+const renderAgentSelection = (choices, selectedKeys, activeIndex) => {
+  output.write("\x1b[2J\x1b[0;0H");
+  printBanner();
+  console.log(brandPrimary.bold("Select agent configs to include"));
+  console.log(uiMuted("Use ↑/↓ to move, space to toggle, enter to confirm."));
+  console.log(uiMuted("Press enter with nothing selected for none."));
+  console.log("");
+
+  choices.forEach((choice, index) => {
+    const isActive = index === activeIndex;
+    const isSelected = selectedKeys.has(choice.key);
+    const cursor = isActive ? ">" : " ";
+    const mark = isSelected ? "x" : " ";
+    const line = `${cursor} [${mark}] ${choice.label}`;
+    if (isActive) {
+      console.log(uiActive.bold(line));
+      return;
+    }
+    if (isSelected) {
+      console.log(uiSelected(line));
+      return;
+    }
+    console.log(uiAccent(line));
+  });
+};
+
+const promptAgentSelection = async (choices, defaultKeys) => {
+  readline.emitKeypressEvents(input);
+  if (input.isTTY) {
+    input.setRawMode(true);
+  }
+
+  const selectedKeys = new Set(defaultKeys);
+  let activeIndex = 0;
+
+  renderAgentSelection(choices, selectedKeys, activeIndex);
+
+  return new Promise((resolve) => {
+    const onKeypress = (_str, key) => {
+      if (key.name === "up") {
+        activeIndex = (activeIndex - 1 + choices.length) % choices.length;
+        renderAgentSelection(choices, selectedKeys, activeIndex);
+        return;
+      }
+      if (key.name === "down") {
+        activeIndex = (activeIndex + 1) % choices.length;
+        renderAgentSelection(choices, selectedKeys, activeIndex);
+        return;
+      }
+      if (key.name === "space") {
+        const choice = choices[activeIndex];
+        if (selectedKeys.has(choice.key)) {
+          selectedKeys.delete(choice.key);
+        } else {
+          selectedKeys.add(choice.key);
+        }
+        renderAgentSelection(choices, selectedKeys, activeIndex);
+        return;
+      }
+      if (key.name === "return") {
+        input.off("keypress", onKeypress);
+        if (input.isTTY) {
+          input.setRawMode(false);
+        }
+        output.write("\n");
+        resolve(selectedKeys);
+      }
+    };
+
+    input.on("keypress", onKeypress);
+  });
+};
+
 const main = async () => {
   const empty = await isEmptyDir(targetDir);
   if (!empty) {
@@ -89,10 +214,20 @@ const main = async () => {
     await fs.copy(examplePath, targetDir, { overwrite: true });
   }
 
+  const existingAgentKeys = await getExistingAgentKeys(targetDir);
+  const defaultKeys = agentDirectories.filter((dir) => existingAgentKeys.has(dir.key)).map((dir) => dir.key);
+
+  const selectedKeys = await promptAgentSelection(agentDirectories, defaultKeys);
+  const selectedLabels = agentDirectories.filter((dir) => selectedKeys.has(dir.key)).map((dir) => dir.label);
+
+  const dirsToRemove = agentDirectories.filter((dir) => !selectedKeys.has(dir.key));
+  await Promise.all(dirsToRemove.map((dir) => fs.remove(path.join(targetDir, dir.path))));
+
+  const appName = path.basename(targetDir);
   const targetPackageJson = path.join(targetDir, "package.json");
   if (fs.existsSync(targetPackageJson)) {
     const pkg = await fs.readJson(targetPackageJson);
-    pkg.name = path.basename(targetDir);
+    pkg.name = appName;
     await fs.writeJson(targetPackageJson, pkg, { spaces: 2 });
   }
 
@@ -104,7 +239,25 @@ const main = async () => {
     runInstall(targetDir, pm);
   }
 
-  console.log(chalk.green("Project created successfully."));
+  printBanner();
+  console.log(
+    [
+      brandPrimary.bold("Project created successfully."),
+      "",
+      uiMuted(`Agent configs: ${selectedLabels.length > 0 ? selectedLabels.join(", ") : "none"}`),
+      "",
+      brandPrimary("Next steps"),
+      uiAccent(`  cd ${appName}`),
+      options.skipInstall ? uiAccent("  npm install") : null,
+      uiAccent("  npm run start"),
+      "",
+      brandPrimary("Then"),
+      uiMuted("  - Build a dev client (if you haven’t): npx expo run:ios / npx expo run:android"),
+      uiMuted("  - Open the app from the dev client on your device or simulator"),
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  );
 };
 
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-twinbloc-app",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React Native starter template with optional examples",
   "type": "module",
   "bin": {