create-pika-minigame 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# create-pika-minigame
+
+CLI tool to scaffold Pika mini-game projects with standalone development environment.
+
+## Usage
+
+```bash
+npx create-pika-minigame my-awesome-game
+cd my-awesome-game
+yarn install
+yarn dev
+```
+
+## What's Included
+
+- **Design System Tokens** - Colors, spacing, typography aligned with Pika brand
+- **UI Components** - Button, Card, TopBar, Spinner
+- **Mock Host** - Test native features without the main app
+- **Re.Pack Config** - Module Federation setup for production
+- **TypeScript** - Full type safety
+
+## Publishing
+
+```bash
+cd tools/create-pika-minigame
+npm publish
+```
+
+## Development
+
+```bash
+# Test the CLI locally
+node bin/cli.js test-game
+
+# Or link globally
+npm link
+create-pika-minigame test-game
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+
+const log = {
+  info: (msg) => console.log(`${colors.cyan}info${colors.reset} ${msg}`),
+  success: (msg) => console.log(`${colors.green}success${colors.reset} ${msg}`),
+  warn: (msg) => console.log(`${colors.yellow}warn${colors.reset} ${msg}`),
+  error: (msg) => console.log(`${colors.red}error${colors.reset} ${msg}`),
+  step: (num, msg) => console.log(`\n${colors.bright}[${num}]${colors.reset} ${msg}`),
+};
+
+function showHelp() {
+  console.log(`
+${colors.bright}create-pika-minigame${colors.reset} - Scaffold a new Pika mini-game project
+
+${colors.bright}Usage:${colors.reset}
+  npx create-pika-minigame <project-name> [options]
+
+${colors.bright}Options:${colors.reset}
+  --help, -h     Show this help message
+  --version, -v  Show version
+
+${colors.bright}Examples:${colors.reset}
+  npx create-pika-minigame my-awesome-game
+  npx create-pika-minigame pronunciation-game
+  npx create-pika-minigame quiz-game
+
+${colors.bright}After creation:${colors.reset}
+  cd <project-name>
+  yarn install
+  yarn dev        # Run with mock host (standalone)
+  yarn build:ios  # Build for production
+`);
+}
+
+function showVersion() {
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+}
+
+function toKebabCase(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+function toPascalCase(str) {
+  return str
+    .split(/[-_\s]+/)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+}
+
+function toSnakeCase(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase();
+}
+
+function copyDir(src, dest, replacements = {}) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    let destName = entry.name.replace('.template', '');
+    const destPath = path.join(dest, destName);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, replacements);
+    } else {
+      let content = fs.readFileSync(srcPath, 'utf8');
+
+      // Apply replacements
+      for (const [key, value] of Object.entries(replacements)) {
+        content = content.replace(new RegExp(`{{${key}}}`, 'g'), value);
+      }
+
+      fs.writeFileSync(destPath, content);
+    }
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  // Handle flags
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    showVersion();
+    process.exit(0);
+  }
+
+  const projectName = args[0];
+
+  if (!projectName) {
+    log.error('Please specify a project name:');
+    console.log('  npx create-pika-minigame my-awesome-game');
+    process.exit(1);
+  }
+
+  // Validate project name
+  if (!/^[a-zA-Z][a-zA-Z0-9-_]*$/.test(projectName)) {
+    log.error('Project name must start with a letter and contain only letters, numbers, hyphens, and underscores.');
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    log.error(`Directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+
+  console.log(`
+${colors.bright}${colors.cyan}
+  ____  _ _         __  __ _       _    ____
+ |  _ \\(_) | ____ _|  \\/  (_)_ __ (_)  / ___| __ _ _ __ ___   ___
+ | |_) | | |/ / _\` | |\\/| | | '_ \\| | | |  _ / _\` | '_ \` _ \\ / _ \\
+ |  __/| |   < (_| | |  | | | | | | | | |_| | (_| | | | | | |  __/
+ |_|   |_|_|\\_\\__,_|_|  |_|_|_| |_|_|  \\____|\\__,_|_| |_| |_|\\___|
+${colors.reset}
+`);
+
+  log.info(`Creating a new Pika mini-game in ${colors.bright}${targetDir}${colors.reset}`);
+
+  const kebabName = toKebabCase(projectName);
+  const pascalName = toPascalCase(projectName);
+  const snakeName = toSnakeCase(projectName);
+
+  const replacements = {
+    PROJECT_NAME: projectName,
+    PROJECT_NAME_KEBAB: kebabName,
+    PROJECT_NAME_PASCAL: pascalName,
+    PROJECT_NAME_SNAKE: snakeName,
+    YEAR: new Date().getFullYear().toString(),
+  };
+
+  log.step(1, 'Creating project structure...');
+
+  const templatesDir = path.join(__dirname, '..', 'templates');
+  copyDir(templatesDir, targetDir, replacements);
+
+  log.step(2, 'Project created successfully!');
+
+  console.log(`
+${colors.green}Success!${colors.reset} Created ${colors.bright}${projectName}${colors.reset} at ${targetDir}
+
+${colors.bright}Next steps:${colors.reset}
+
+  ${colors.cyan}cd ${projectName}${colors.reset}
+  ${colors.cyan}yarn install${colors.reset}
+
+${colors.bright}Available commands:${colors.reset}
+
+  ${colors.cyan}yarn dev${colors.reset}          Start development with mock host (standalone)
+  ${colors.cyan}yarn build:ios${colors.reset}   Build for iOS production
+  ${colors.cyan}yarn build:android${colors.reset} Build for Android production
+  ${colors.cyan}yarn deploy${colors.reset}      Deploy to CDN (requires setup)
+
+${colors.bright}Documentation:${colors.reset}
+  See README.md in your project for detailed instructions.
+
+Happy coding! ${colors.yellow}🎮${colors.reset}
+`);
+}
+
+main();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-pika-minigame",
+  "version": "1.0.0",
+  "description": "CLI to scaffold Pika mini-game projects with standalone dev environment",
+  "author": "Pika Team",
+  "license": "MIT",
+  "bin": {
+    "create-pika-minigame": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "keywords": [
+    "pika",
+    "mini-game",
+    "react-native",
+    "module-federation",
+    "repack"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pika/create-pika-minigame"
+  }
+}

package/templates/README.md

@@ -0,0 +1,196 @@
+# {{PROJECT_NAME_PASCAL}}
+
+A Pika mini-game built with React Native and Module Federation.
+
+## Quick Start
+
+```bash
+# Install dependencies
+yarn install
+
+# Run in development mode (standalone with mock host)
+yarn dev
+
+# Build for production
+yarn build:ios
+yarn build:android
+```
+
+## Project Structure
+
+```
+{{PROJECT_NAME_KEBAB}}/
+├── src/                    # Your game source code
+│   ├── App.tsx             # Main entry component
+│   ├── tokens.ts           # Design system tokens
+│   ├── types.ts            # TypeScript types
+│   └── components/         # Reusable UI components
+│       ├── Button.tsx
+│       ├── Card.tsx
+│       ├── TopBar.tsx
+│       └── Spinner.tsx
+│
+├── dev/                    # Standalone development
+│   ├── index.js            # Dev entry point
+│   ├── DevApp.tsx          # Wrapper with mock host
+│   └── MockHost.ts         # Mock native capabilities
+│
+├── index.js                # Production entry (Module Federation)
+├── rspack.config.mjs       # Re.Pack bundler config
+├── app.json                # Expo config (for dev mode)
+└── package.json
+```
+
+## Development
+
+### Running Standalone
+
+The `yarn dev` command runs your mini-game as a standalone Expo app with a mocked host bridge. This lets you:
+
+- Develop without the main Pika app
+- Test UI and game logic independently
+- See console logs for mock API calls
+
+### Mock Host
+
+Edit `dev/MockHost.ts` to customize mock behavior:
+
+```typescript
+// Return specific scores for testing
+stopAndCheck: async (word) => ({
+  totalScore: 95,  // Always high score
+  words: [{ word, score: 95, letters: [...] }]
+})
+
+// Simulate errors
+startRecording: async () => {
+  throw new Error('Microphone permission denied');
+}
+
+// Add delays for loading state testing
+await delay(3000);
+```
+
+## Design System
+
+### Tokens
+
+Use tokens from `src/tokens.ts` for consistent styling:
+
+```typescript
+import { color, semantic, space, radius, typography } from './tokens';
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: semantic.bg,        // Dark background
+    padding: space[4],                   // 16px
+    borderRadius: radius.lg,             // 16px
+  },
+  title: {
+    color: semantic.text,                // White
+    fontSize: typography.title1.size,    // 28
+    fontWeight: typography.title1.fontWeight,
+  },
+});
+```
+
+### Components
+
+Pre-built components in `src/components/`:
+
+```typescript
+import { Button, Card, TopBar, Spinner } from './components';
+
+// Button variants: primary, secondary, danger, ghost
+<Button label="Start" variant="primary" size="lg" onPress={...} />
+
+// Card with press interaction
+<Card onPress={...}>
+  <Text>Tap me</Text>
+</Card>
+
+// TopBar with back/close buttons
+<TopBar left="back" onLeftPress={goBack} title="Game" />
+
+// Loading spinner
+<Spinner size="lg" color={color.cyan[400]} />
+```
+
+## Host Bridge
+
+The `host` prop provides native capabilities from the main app:
+
+```typescript
+interface HostBridge {
+  pronunciation: {
+    startRecording: () => Promise<void>;
+    stopAndCheck: (word: string) => Promise<PronunciationResult>;
+    cancel: () => Promise<void>;
+  };
+}
+```
+
+Usage in your game:
+
+```typescript
+const App: React.FC<GameProps> = ({ host }) => {
+  const startRecording = async () => {
+    await host?.pronunciation.startRecording();
+  };
+
+  const checkPronunciation = async (word: string) => {
+    const result = await host?.pronunciation.stopAndCheck(word);
+    console.log('Score:', result.totalScore);
+  };
+};
+```
+
+## Building for Production
+
+### 1. Build the bundle
+
+```bash
+# iOS
+yarn build:ios
+
+# Android
+yarn build:android
+```
+
+### 2. Serve locally for testing
+
+```bash
+yarn serve:ios   # Serves on http://localhost:9000
+```
+
+### 3. Deploy to CDN
+
+Edit `package.json` to add your deployment command:
+
+```json
+{
+  "scripts": {
+    "deploy:ios": "MF_PUBLIC_PATH=https://your-cdn.com/games/{{PROJECT_NAME_KEBAB}}/ yarn build:ios && <your-deploy-command>"
+  }
+}
+```
+
+## Integration with Pika App
+
+Once deployed, the main Pika app can load your mini-game:
+
+```typescript
+// In the host app
+const game = await loadRemote('{{PROJECT_NAME_SNAKE}}/App');
+```
+
+## Tips
+
+1. **Test on real devices** - Mock host simulates behavior, but test on device for real performance
+2. **Keep it fast** - Mini-games should load instantly; minimize bundle size
+3. **Handle errors** - Always check if `host` is defined before using
+4. **Dark theme** - Default tokens are dark-themed for immersive game feel
+
+## License
+
+MIT © {{YEAR}} Pika Team

package/templates/app.json.template

@@ -0,0 +1,29 @@
+{
+  "expo": {
+    "name": "{{PROJECT_NAME_PASCAL}}",
+    "slug": "{{PROJECT_NAME_KEBAB}}",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "dark",
+    "splash": {
+      "image": "./assets/splash.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#0B0B0B"
+    },
+    "ios": {
+      "supportsTablet": true,
+      "bundleIdentifier": "com.pika.minigame.{{PROJECT_NAME_KEBAB}}"
+    },
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/adaptive-icon.png",
+        "backgroundColor": "#0B0B0B"
+      },
+      "package": "com.pika.minigame.{{PROJECT_NAME_SNAKE}}"
+    },
+    "plugins": [
+      "expo-router"
+    ]
+  }
+}

package/templates/babel.config.js

@@ -0,0 +1,7 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['react-native-reanimated/plugin'],
+  };
+};

package/templates/dev/DevApp.tsx

@@ -0,0 +1,47 @@
+/**
+ * Development wrapper for standalone mini-game testing.
+ *
+ * This wraps your App component with a mock host bridge
+ * so you can develop and test without the main Pika app.
+ *
+ * Run with: yarn dev
+ */
+
+import React from 'react';
+import { Alert } from 'react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+
+import App from '../src/App';
+import mockHost from './MockHost';
+
+export default function DevApp() {
+  const handleExit = () => {
+    Alert.alert(
+      'Exit Pressed',
+      'In the real app, this would close the mini-game and return to the main app.',
+      [{ text: 'OK' }]
+    );
+  };
+
+  const handleGameOver = (result: { score: number }) => {
+    console.log('[DevApp] Game over with score:', result.score);
+    Alert.alert(
+      'Game Over!',
+      `Your score: ${result.score}\n\nIn the real app, this score would be saved.`,
+      [{ text: 'OK' }]
+    );
+  };
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <SafeAreaProvider>
+        <App
+          host={mockHost}
+          onExit={handleExit}
+          onGameOver={handleGameOver}
+        />
+      </SafeAreaProvider>
+    </GestureHandlerRootView>
+  );
+}

package/templates/dev/MockHost.ts

@@ -0,0 +1,131 @@
+/**
+ * Mock Host Bridge for standalone development.
+ *
+ * This simulates the host app's native capabilities so you can
+ * develop and test your mini-game without the main app.
+ */
+
+import { HostBridge, PronunciationResult } from '../src/types';
+
+// Simulate recording state
+let isRecording = false;
+
+/**
+ * Generate a random score for testing different UI states.
+ */
+const randomScore = (min = 40, max = 100): number =>
+  Math.floor(Math.random() * (max - min + 1)) + min;
+
+/**
+ * Generate letter-by-letter scores for a word.
+ */
+const generateLetterScores = (word: string) =>
+  [...word].map((letter) => ({
+    letter,
+    score: randomScore(50, 100),
+  }));
+
+/**
+ * Simulate async delay (like network/native calls).
+ */
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Mock implementation of the host bridge.
+ * Edit these to test different scenarios.
+ */
+export const mockHost: HostBridge = {
+  pronunciation: {
+    startRecording: async () => {
+      if (isRecording) {
+        console.warn('[MockHost] Already recording');
+        return;
+      }
+      console.log('[MockHost] 🎤 Recording started...');
+      isRecording = true;
+      // Simulate recording initialization delay
+      await delay(100);
+    },
+
+    stopAndCheck: async (targetWord: string): Promise<PronunciationResult> => {
+      if (!isRecording) {
+        console.warn('[MockHost] Not recording');
+        throw new Error('Not recording');
+      }
+
+      console.log(`[MockHost] 🛑 Recording stopped. Checking: "${targetWord}"`);
+      isRecording = false;
+
+      // Simulate processing delay (like API call)
+      await delay(800 + Math.random() * 500);
+
+      // Generate mock result
+      const wordScore = randomScore(50, 100);
+      const letters = generateLetterScores(targetWord);
+      const totalScore = Math.round(
+        letters.reduce((sum, l) => sum + l.score, 0) / letters.length
+      );
+
+      console.log(`[MockHost] ✅ Score: ${totalScore}`);
+
+      return {
+        totalScore,
+        words: [
+          {
+            word: targetWord,
+            score: wordScore,
+            letters,
+          },
+        ],
+      };
+    },
+
+    cancel: async () => {
+      console.log('[MockHost] ❌ Recording cancelled');
+      isRecording = false;
+    },
+  },
+
+  // Add more mock capabilities here as needed:
+  // audio: {
+  //   play: async (url) => console.log(`[MockHost] Playing: ${url}`),
+  //   stop: () => console.log('[MockHost] Audio stopped'),
+  // },
+  // haptics: {
+  //   impact: (style) => console.log(`[MockHost] Haptic: ${style}`),
+  // },
+};
+
+/**
+ * Mock host that always fails - useful for testing error states.
+ */
+export const mockHostWithErrors: HostBridge = {
+  pronunciation: {
+    startRecording: async () => {
+      throw new Error('Microphone permission denied');
+    },
+    stopAndCheck: async () => {
+      throw new Error('Speech recognition failed');
+    },
+    cancel: async () => {},
+  },
+};
+
+/**
+ * Mock host with slow responses - useful for testing loading states.
+ */
+export const mockHostSlow: HostBridge = {
+  pronunciation: {
+    startRecording: async () => {
+      await delay(2000);
+      console.log('[MockHost Slow] Recording started after delay');
+    },
+    stopAndCheck: async (word) => {
+      await delay(3000);
+      return mockHost.pronunciation.stopAndCheck(word);
+    },
+    cancel: async () => {},
+  },
+};
+
+export default mockHost;

package/templates/dev/index.js

@@ -0,0 +1,9 @@
+/**
+ * Development entry point.
+ * This is used by Expo to run the mini-game standalone.
+ */
+
+import { registerRootComponent } from 'expo';
+import DevApp from './DevApp';
+
+registerRootComponent(DevApp);

package/templates/index.js

@@ -0,0 +1,8 @@
+/**
+ * Production entry point for Module Federation.
+ * This is bundled by Re.Pack and loaded by the host app.
+ */
+
+import App from './src/App';
+
+export default App;