kappmaker 1.0.0

package/README.md

@@ -0,0 +1,545 @@
+# KAppMaker CLI
+
+CLI tool for automating mobile app bootstrapping for the KAppMaker platform. Handles everything from template cloning and Firebase setup to App Store Connect configuration, Adapty subscriptions, AI logo generation, and Android release builds.
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| [`kappmaker create <app-name>`](#create-app-name) | Full end-to-end app setup (Firebase, logo, App Store, Adapty, release build) |
+| [`kappmaker create-logo`](#create-logo) | Generate an app logo with AI (fal.ai) |
+| [`kappmaker create-appstore-app`](#create-appstore-app) | Set up an app on App Store Connect (metadata, subscriptions, privacy) |
+| [`kappmaker adapty setup`](#adapty-setup) | Set up Adapty products, paywalls, and placements |
+| [`kappmaker image-split <image>`](#image-split-source) | Split a grid image into individual tiles |
+| [`kappmaker image-remove-bg <image>`](#image-remove-bg-source) | Remove background from an image (fal.ai) |
+| [`kappmaker image-enhance <image>`](#image-enhance-source) | Upscale and enhance image quality (fal.ai) |
+| [`kappmaker translate-screenshots [dir]`](#translate-screenshots-source-dir) | Translate screenshots to multiple locales (fal.ai) |
+| [`kappmaker generate-screenshots`](#generate-screenshots) | Generate marketing screenshots with AI (OpenAI + fal.ai) |
+| [`kappmaker config`](#config) | Manage CLI settings, API keys, and global defaults |
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 20
+- **Git**
+- **Firebase CLI** — `npm install -g firebase-tools`
+- **CocoaPods** — `sudo gem install cocoapods`
+- **Fastlane** — via Bundler in the template repo
+- **Android SDK** — installed at `~/Library/Android/sdk` (configurable)
+- **asc CLI** (optional, for App Store Connect) — `brew install asc`
+- **Adapty CLI** (optional, for Adapty setup) — `npm install -g adapty`
+
+## External Services & API Keys
+
+The CLI integrates with several external services for AI image generation, app store management, and subscription setup. All keys are stored locally at `~/.config/kappmaker/config.json`.
+
+### fal.ai — AI Image Generation
+
+**Used for:** Logo generation, background removal, image enhancement, screenshot translation, and screenshot generation.
+
+**How to get your key:**
+1. Sign up at [fal.ai](https://fal.ai)
+2. Go to [Dashboard > Keys](https://fal.ai/dashboard/keys) and create an API key
+3. `kappmaker config set falApiKey <your-key>`
+
+### ImgBB — Image Hosting
+
+**Used for:** Temporarily hosting reference images when generating or translating screenshots (fal.ai needs a public URL to process images).
+
+**How to get your key:**
+1. Sign up at [imgbb.com](https://imgbb.com)
+2. Go to [api.imgbb.com](https://api.imgbb.com/) and get your free API key
+3. `kappmaker config set imgbbApiKey <your-key>`
+
+### OpenAI — Prompt Generation
+
+**Used for:** Generating detailed screenshot specifications from a short app description (uses GPT-4.1). Only needed for the `generate-screenshots` command.
+
+**How to get your key:**
+1. Sign up at [platform.openai.com](https://platform.openai.com)
+2. Go to [API Keys](https://platform.openai.com/api-keys) and create a new key
+3. `kappmaker config set openaiApiKey <your-key>`
+
+### App Store Connect CLI (asc) — iOS App Management
+
+**Used for:** Creating apps, setting metadata, categories, subscriptions, privacy declarations, and review info on App Store Connect.
+
+**How to set up:**
+1. Install: `brew install asc`
+2. Generate an API key at [App Store Connect > Users and Access > Integrations > API](https://appstoreconnect.apple.com/access/integrations/api) (Admin role, download the `.p8` file immediately)
+3. Configure:
+   ```bash
+   kappmaker config set ascKeyId <your-key-id>
+   kappmaker config set ascIssuerId <your-issuer-id>
+   kappmaker config set ascPrivateKeyPath /path/to/AuthKey.p8
+   kappmaker config set appleId your@email.com
+   ```
+   Or run `kappmaker config appstore-defaults --init` for interactive setup.
+
+### Adapty CLI — Subscription Management
+
+**Used for:** Setting up in-app subscription products, paywalls, and placements across iOS and Android via Adapty's backend.
+
+**How to set up:**
+1. Install: `npm install -g adapty`
+2. Log in: `adapty auth login` (opens browser for authentication)
+3. Run: `kappmaker adapty setup`
+
+### Firebase CLI — Backend Setup
+
+**Used for:** Creating Firebase projects, registering Android/iOS apps, downloading SDK config files (`google-services.json`, `GoogleService-Info.plist`), and enabling anonymous authentication.
+
+**How to set up:**
+1. Install: `npm install -g firebase-tools`
+2. The `create` command handles login and project creation interactively.
+
+---
+
+## Installation
+
+```bash
+npm install -g kappmaker
+```
+
+Then use it anywhere:
+
+```bash
+kappmaker create <AppName>
+```
+
+### Development
+
+```bash
+npm install
+npx tsx src/index.ts create <AppName>
+```
+
+---
+
+## `create <app-name>`
+
+Full end-to-end app bootstrapping. Creates a new KAppMaker app from the template and optionally sets up everything needed to publish.
+
+```bash
+kappmaker create Remimi
+```
+
+**What it does (13 steps):**
+
+| Step | Action | Details |
+|------|--------|---------|
+| 1 | Clone template | Clones into `<AppName>-All/` (prompts to overwrite if exists) |
+| 2 | Firebase login | Opens browser for authentication |
+| 3 | Create Firebase project | `<appname>-app` (skips if exists) |
+| 4 | Create Firebase apps | Android + iOS apps (reuses existing if found) |
+| 5 | Enable anonymous auth | Via Identity Toolkit REST API (warns on failure) |
+| 6 | Download SDK configs | `google-services.json` + `GoogleService-Info.plist` |
+| 7 | Logo generation | *Optional* — AI logo + automatic background removal |
+| 8 | App Store Connect | *Optional* — full app setup (metadata, subs, privacy) |
+| 9 | Adapty setup | *Optional* — products, paywalls, placements |
+| 10 | Gradle refactor | Sets app name + application ID; asks whether to also rename the package name (default: yes) |
+| 11 | Build environment | Creates `local.properties`, installs CocoaPods |
+| 12 | Git remotes | Renames origin to upstream |
+| 13 | Android release build | Fastlane build, prints AAB path for Google Play upload |
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--template-repo <url>` | Template repository URL | KAppMaker template |
+| `--organization <org>` | Organization for Fastlane signing | App name (configurable) |
+
+---
+
+## `create-logo`
+
+Generates an app logo using fal.ai's nano-banana-2 model.
+
+```bash
+kappmaker create-logo
+kappmaker create-logo --output ./custom/path/logo.png
+```
+
+**Flow:**
+1. Prompts for app idea / description
+2. Generates a 4x4 grid of 16 logo variations (2K, 1:1)
+3. Opens grid in Preview.app for review
+4. Pick a logo (1-16) or R to regenerate — optional: `5 --zoom 1.1 --gap 3`
+5. Extracts chosen logo at 512x512
+
+**Output:** `Assets/app_logo.png` + `Assets/logo_variations.png`
+
+Requires: `kappmaker config set falApiKey <your-key>`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output <path>` | Custom output path | `Assets/app_logo.png` |
+
+---
+
+## `create-appstore-app`
+
+Creates and fully configures an app on App Store Connect using the [asc CLI](https://github.com/rudrankriyam/App-Store-Connect-CLI).
+
+```bash
+kappmaker create-appstore-app
+kappmaker create-appstore-app --config ./my-config.json
+```
+
+### First-time setup
+
+1. **Generate an API key** at [App Store Connect > Users and Access > Integrations > API](https://appstoreconnect.apple.com/access/integrations/api) — Admin access, download the `.p8` file immediately
+2. **Run one-time setup:**
+   ```bash
+   kappmaker config appstore-defaults --init
+   ```
+
+### What it does (13 steps)
+
+1. Validate asc CLI and authentication
+2. Load config (from file or interactive prompts)
+3. Register Bundle ID
+4. Find or create app
+5. Set content rights
+6. Create app version (1.0.0)
+7. Set categories
+8. Set age rating
+9. Update localizations
+10. Set pricing, availability, and subscriptions
+11. Set privacy data usages
+12. Set encryption declarations
+13. Set review contact details
+
+### Config resolution
+
+Layers are deep-merged (later overrides earlier):
+
+1. **Built-in template** — age rating, privacy, encryption, subscriptions
+2. **Global defaults** (`~/.config/kappmaker/appstore-defaults.json`) — review contact, copyright
+3. **Local config** (`./Assets/appstore-config.json` or `--config`)
+4. **Interactive prompts** — only for fields still empty
+
+### Default subscriptions
+
+| Subscription | Period | Price | Product ID |
+|-------------|--------|-------|------------|
+| Weekly Premium | `ONE_WEEK` | $6.99 | `{appname}.premium.weekly.v1.699.v1` |
+| Yearly Premium | `ONE_YEAR` | $29.99 | `{appname}.premium.yearly.v1.2999.v1` |
+
+Auto-generated naming: group `{appname}.premium.v1`, ref name `{AppName} Premium Weekly v1 (6.99)`.
+
+### Default privacy
+
+| Data Category | Purpose | Protection |
+|--------------|---------|------------|
+| User ID | App Functionality | Linked to You |
+| Device ID | App Functionality | Linked to You |
+| Crash Data | Analytics | Not Linked to You |
+| Performance Data | Analytics | Not Linked to You |
+| Other Diagnostic Data | Analytics | Not Linked to You |
+| Other Usage Data | Analytics | Not Linked to You |
+| Product Interaction | Analytics | Not Linked to You |
+
+During interactive setup, the CLI asks if the app accesses user content (AI image/video wrapper). If yes, adds Photos or Videos + Other User Content (both App Functionality / Not Linked to You).
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--config <path>` | Path to JSON config file | `./Assets/appstore-config.json` |
+
+---
+
+## `adapty setup`
+
+Sets up Adapty subscription products, paywalls, and placements using the [Adapty CLI](https://github.com/adaptyteam/adapty-cli).
+
+```bash
+kappmaker adapty setup
+kappmaker adapty setup --config ./my-config.json
+```
+
+**Prerequisites:** Install (`npm install -g adapty`) and log in (`adapty auth login`).
+
+### What it does (8 steps)
+
+1. Validate CLI and authentication
+2. Load config (from file or interactive prompts)
+3. Find or create app (iOS + Android)
+4. Create "Premium" access level
+5. Create products
+6. Create paywalls (linking products)
+7. Create placements (linking paywalls)
+
+### Default products
+
+| Product | Period | Price | iOS Product ID | Android Base Plan ID |
+|---------|--------|-------|----------------|---------------------|
+| Weekly Premium | `weekly` | $6.99 | `{appname}.premium.weekly.v1.699.v1` | `autorenew-weekly-price-v1` |
+| Yearly Premium | `annual` | $29.99 | `{appname}.premium.yearly.v1.2999.v1` | `autorenew-yearly-price-v1` |
+
+iOS product IDs match the App Store Connect format so they align across both systems.
+
+### Default paywalls and placements
+
+| Paywall | Products | Placement | Developer ID |
+|---------|----------|-----------|-------------|
+| Default Paywall | Weekly + Yearly | Default | `default` |
+| Onboarding Paywall | Weekly + Yearly | Onboarding | `onboarding` |
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--config <path>` | Path to JSON config file | `./Assets/adapty-config.json` |
+
+---
+
+## Image Tools
+
+AI-powered image commands. Require a fal.ai API key: `kappmaker config set falApiKey <your-key>`
+
+### `image-split <source>`
+
+Splits a grid image into individual tiles.
+
+```bash
+kappmaker image-split grid.png --rows 4 --cols 4 --zoom 1.1 --gap 3
+kappmaker image-split grid.png --keep 1,5    # Keep only tiles 1 and 5
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--rows <n>` | Number of rows | `4` |
+| `--cols <n>` | Number of columns | `4` |
+| `--zoom <factor>` | Zoom factor to crop edges | `1.07` |
+| `--gap <pixels>` | Gap pixels at each tile edge | `0` |
+| `--width <pixels>` | Output tile width | `512` |
+| `--height <pixels>` | Output tile height | `512` |
+| `--output-dir <path>` | Directory to save tiles | `.` |
+| `--keep <indices>` | Comma-separated tile indices to keep | All |
+
+### `image-remove-bg <source>`
+
+Removes background using fal.ai bria model. Outputs PNG with transparency.
+
+```bash
+kappmaker image-remove-bg logo.png
+kappmaker image-remove-bg photo.jpg --output clean.png
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output <path>` | Custom output path | `<filename>_no_bg.png` |
+
+### `image-enhance <source>`
+
+Upscales and improves image quality using fal.ai nano-banana-2 edit model.
+
+```bash
+kappmaker image-enhance logo.png
+kappmaker image-enhance photo.jpg --output improved.png
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output <path>` | Custom output path | `<filename>_enhanced.png` |
+
+---
+
+## `translate-screenshots [source-dir]`
+
+Translates app screenshots into multiple locales using fal.ai and saves to Fastlane distribution directories.
+
+```bash
+kappmaker translate-screenshots                                        # Uses default: MobileApp/distribution/.../en-US
+kappmaker translate-screenshots ./screenshots/en-US                    # Custom source dir
+kappmaker translate-screenshots ./screenshots/en-US --locales de-DE ja-JP  # Specific locales
+```
+
+**Flow:**
+1. Combines source images into a 2x4 grid
+2. Submits grid to fal.ai for each locale (all in parallel)
+3. Downloads translated grids, splits back into individual screenshots
+4. Saves to Fastlane iOS/Android directory structure
+
+**Output auto-detection:** If source is inside a distribution structure, the root is detected automatically. Otherwise defaults to `./MobileApp/distribution`.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output <path>` | Distribution directory root | Auto-detected |
+| `--locales <codes...>` | Target locale codes (space-separated) or `all` | All 48 locales |
+| `--rows <n>` | Grid rows | `2` |
+| `--cols <n>` | Grid columns | `4` |
+| `--resolution <res>` | AI resolution (`1K`, `2K`, `4K`) | `2K` |
+| `--poll-interval <seconds>` | Seconds between status checks | `10` |
+
+<details>
+<summary>Supported locales (48 total)</summary>
+
+| Play Store | App Store | | Play Store | App Store |
+|------------|-----------|---|------------|-----------|
+| `ar` | `ar-SA` | | `lt-LT` | — |
+| `bg-BG` | — | | `lv-LV` | — |
+| `bn-BD` | — | | `ms` | `ms` |
+| `ca` | `ca` | | `nl-NL` | `nl-NL` |
+| `cs-CZ` | `cs` | | `no-NO` | `no` |
+| `da-DK` | `da` | | `pl-PL` | `pl` |
+| `de-DE` | `de-DE` | | `pt-BR` | `pt-BR` |
+| `el-GR` | `el` | | `pt-PT` | `pt-PT` |
+| `en-AU` | `en-AU` | | `ro` | `ro` |
+| `en-GB` | `en-GB` | | `ru-RU` | `ru` |
+| `es-ES` | `es-ES` | | `sk` | `sk` |
+| `es-419` | `es-MX` | | `sl-SI` | — |
+| `et-EE` | — | | `sr` | — |
+| `fi-FI` | `fi` | | `sv-SE` | `sv` |
+| `fil` | — | | `sw` | — |
+| `fr-FR` | `fr-FR` | | `ta-IN` | — |
+| `fr-CA` | `fr-CA` | | `te-IN` | — |
+| `he-IL` | `he` | | `th` | `th` |
+| `hi-IN` | `hi` | | `tr-TR` | `tr` |
+| `hr` | `hr` | | `uk` | `uk` |
+| `hu-HU` | `hu` | | `vi` | `vi` |
+| `id` | `id` | | `zh-CN` | `zh-Hans` |
+| `it-IT` | `it` | | `zh-TW` | `zh-Hant` |
+| `ja-JP` | `ja` | | | |
+| `ko-KR` | `ko` | | | |
+
+Locales marked with **—** are Android-only (no App Store equivalent).
+
+</details>
+
+---
+
+## `generate-screenshots`
+
+Generates marketing screenshots using OpenAI (prompt generation) + fal.ai (image generation).
+
+```bash
+kappmaker generate-screenshots --prompt "A fitness tracking app with workout plans"
+kappmaker generate-screenshots --prompt "A meditation app" --input ./my-screenshots
+kappmaker generate-screenshots --prompt "A recipe app" --style 3 --resolution 4K
+```
+
+**Flow:**
+1. OpenAI (GPT-4.1) generates a detailed screenshot specification from your description
+2. fal.ai generates a grid of 8 screenshots (`nano-banana-2`, or `nano-banana-2/edit` with reference images)
+3. Grid is split into individual screenshots
+
+**Output:** `Assets/screenshots/appstore/` + `Assets/screenshots/playstore/` (+ Fastlane dirs if `MobileApp/distribution` exists)
+
+Requires: `falApiKey`, `openaiApiKey`, and `imgbbApiKey` (if using reference images)
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--prompt <text>` | App description (required) | — |
+| `--input <dir>` | Reference screenshot directory | Auto-detect `Assets/screenshots` |
+| `--style <id>` | Style preset (1-8) | `1` |
+| `--output <dir>` | Output base directory | `Assets/screenshots` |
+| `--resolution <res>` | AI resolution (`1K`, `2K`, `4K`) | `2K` |
+
+<details>
+<summary>Screenshot styles (1-8)</summary>
+
+| Style | Description |
+|-------|-------------|
+| `1` | Rich multi-device marketing (bold text, shadows & reflections) |
+| `2` | Minimal Apple-style (single centered device, clean whitespace) |
+| `3` | SaaS conversion-focused (feature bullet callouts) |
+| `4` | Bold geometric color blocks (vibrant split backgrounds) |
+| `5` | Full-bleed UI, no device frames (edge-to-edge with blur overlay) |
+| `6` | Cinematic depth (layered devices, depth-of-field) |
+| `7` | Editorial lifestyle (soft neutral backgrounds, serif type) |
+| `8` | Floating product reveal (Apple keynote aesthetic) |
+
+</details>
+
+---
+
+## `config`
+
+Manage CLI configuration stored at `~/.config/kappmaker/config.json`.
+
+```bash
+kappmaker config init                                    # Interactive setup
+kappmaker config list                                    # Show all values
+kappmaker config set <key> <value>                       # Set a value
+kappmaker config get <key>                               # Get a value
+kappmaker config path                                    # Show config file path
+kappmaker config appstore-defaults                       # View App Store defaults
+kappmaker config appstore-defaults --init                # Set up API key + review contact
+kappmaker config appstore-defaults --save ./config.json  # Save as global defaults
+kappmaker config adapty-defaults                         # View Adapty defaults
+kappmaker config adapty-defaults --save ./config.json    # Save as global defaults
+```
+
+### Config keys
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `templateRepo` | Template repository Git URL | KAppMaker template |
+| `bundleIdPrefix` | Bundle/package ID prefix (e.g., `com.measify`) | `com.<appname>` |
+| `androidSdkPath` | Android SDK location | `~/Library/Android/sdk` |
+| `organization` | Organization for Fastlane signing | App name |
+| `falApiKey` | fal.ai API key | — |
+| `imgbbApiKey` | imgbb API key ([api.imgbb.com](https://api.imgbb.com/)) | — |
+| `openaiApiKey` | OpenAI API key | — |
+| `ascAuthName` | ASC keychain credential name | `KAppMaker` |
+| `ascKeyId` | App Store Connect API Key ID | — |
+| `ascIssuerId` | App Store Connect Issuer ID | — |
+| `ascPrivateKeyPath` | Path to `.p8` private key | — |
+| `appleId` | Apple ID email (for privacy setup) | — |
+
+### Global defaults
+
+| File | Used by | Manage with |
+|------|---------|-------------|
+| `~/.config/kappmaker/appstore-defaults.json` | `create-appstore-app` | `config appstore-defaults` |
+| `~/.config/kappmaker/adapty-defaults.json` | `adapty setup` | `config adapty-defaults` |
+
+Global defaults are merged as a base layer so shared settings (review contact, privacy, subscriptions, etc.) don't need to be re-entered per app.
+
+---
+
+## Project Structure
+
+```
+src/
+  index.ts                  # Entry point
+  cli.ts                    # Command registration (Commander.js)
+  commands/
+    create.ts               # Full app setup (13-step orchestrator)
+    create-logo.ts          # AI logo generation
+    create-appstore-app.ts  # App Store Connect setup (13-step orchestrator)
+    adapty-setup.ts         # Adapty setup (8-step orchestrator)
+    split.ts                # Grid image splitter
+    remove-bg.ts            # Background removal
+    enhance.ts              # Image quality enhancement
+    translate-screenshots.ts # Screenshot translation
+    generate-screenshots.ts # AI screenshot generation
+    config.ts               # Config management
+  services/
+    firebase.service.ts     # Firebase CLI wrapper + anonymous auth
+    fal.service.ts          # fal.ai API (generation, translation, screenshots)
+    openai.service.ts       # OpenAI API (prompt generation)
+    asc.service.ts          # App Store Connect CLI wrapper
+    asc-monetization.service.ts  # ASC pricing, subscriptions, IAP
+    adapty.service.ts       # Adapty CLI wrapper
+    git.service.ts          # Git operations
+    gradle.service.ts       # Gradle build operations
+    ios.service.ts          # CocoaPods setup
+    fastlane.service.ts     # Fastlane build + AAB finder
+    logo.service.ts         # Logo prompt builder + image extraction
+    screenshot.service.ts   # Screenshot grid operations + Fastlane output
+    screenshot-styles.ts    # Screenshot style prompts (8 styles)
+  utils/
+    logger.ts               # Chalk-based logging
+    exec.ts                 # Command execution (execa + ora)
+    validator.ts            # Dependency and input validation
+    config.ts               # User config management
+    prompt.ts               # Interactive prompts
+  templates/
+    appstore-config.json    # Default App Store Connect config
+    adapty-config.json      # Default Adapty config
+  types/
+    index.ts                # Shared interfaces
+    appstore.ts             # App Store Connect types
+    adapty.ts               # Adapty types
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createCli(): Command;