@gopay/minikit-cli 1.2.1

package/README.md

@@ -0,0 +1,322 @@
+# @gopay/minikit-cli
+
+A CLI tool for scaffolding and managing GoPay mini-app web projects.
+
+## Prerequisites
+
+**Bun** — a fast JavaScript runtime and package manager used to run the CLI.
+
+```bash
+bun --version
+```
+
+If it's not installed:
+
+```bash
+curl -fsSL https://bun.com/install | bash -s "bun-v1.3.14"
+```
+
+## Installation
+
+```bash
+bun install -g @gopay/minikit-cli
+```
+
+Verify the installation:
+
+```bash
+minikit-cli --version
+```
+
+## Complete Command Reference
+
+### Command Groups
+
+| Group | Commands |
+|---|---|
+| **Project scaffolding** | `create` |
+| **Feature commands** | `jsbridge:add`, `jsbridge:remove`, `i18n:add`, `snap:add`, `vconsole:add` |
+| **CLI management** | `update`, `migrate` |
+| **Utilities** | `docs`, `--help` |
+
+<a name="create"></a>
+
+## `create`
+
+Scaffolds a new mini-app project interactively.
+
+```bash
+minikit-cli create [project_name] [options]
+```
+
+**Arguments**
+
+| Argument | Required | Description |
+|---|---|---|
+| `project_name` | No (prompted) | Name of the project to create |
+
+**Options**
+
+| Flag | Description |
+|---|---|
+| `--no-install` | Skip dependency installation |
+| `--project-dir <path>` | Target directory to create the project in (defaults to current directory) |
+
+**Examples**
+
+```bash
+# Fully interactive — prompts for everything
+minikit-cli create
+
+# Skip the name prompt, still prompts for features
+minikit-cli create my-app
+
+# Create project without installing dependencies
+minikit-cli create my-app --no-install
+
+# Create project in a specific directory
+minikit-cli create my-app --project-dir /tmp/scaffolds --no-install
+```
+
+**Interactive prompt flow**
+
+When run interactively (with a TTY), the wizard walks through the following steps in order:
+
+1. **Project name** — text input (skipped if passed as an argument)
+   ```
+   Project name? › my-app
+   ```
+
+2. **Framework** — single select
+   ```
+   Choose framework:
+   ● React + TypeScript
+   ```
+
+3. **Install dependencies** — confirmation
+   ```
+   Install dependencies with pnpm? › yes / no
+   ```
+
+4. **Features** — multi-select (space to toggle, enter to confirm)
+   ```
+   Select features to include:
+   ◯ Auth
+   ◯ i18n
+   ◯ Snap Checkout
+   ```
+
+5. **Per-feature options** — shown immediately after each selected feature. For example, selecting **Auth** shows:
+   ```
+   When to fetch auth code?
+   ● Before app renders (fetch Auth Code first)
+   ○ After app renders (fetch Auth Code after UI loads)
+   ```
+
+6. **Debug tools** — multi-select
+   ```
+   Select debug tools:
+   ◯ vConsole
+   ```
+
+**After the wizard completes**, the CLI prints next steps:
+
+```
+1. cd my-app
+2. source "$HOME/.nvm/nvm.sh" && nvm use
+3. cp .env.example .env  (update .env values based on your project)
+4. pnpm install          (only shown if deps were not installed)
+5. pnpm dev
+```
+
+**Important notes:**
+
+- **NVM (`source "$HOME/.nvm/nvm.sh" && nvm use`):** Loads the NVM shell integration and switches to the Node version specified in `.nvmrc`. Run this every time you:
+  - Switch to a different project folder
+  - Open a new terminal/shell session
+  - If nvm isn't configured to auto-load in your shell config (`.bashrc`, `.zshrc`)
+  - This ensures `pnpm` and other tools use the correct Node version for your project
+
+- **`.env` configuration:** After copying `.env.example` to `.env`, **update the values according to your project requirements**. Each environment variable is documented in the `.env.example` file with examples and descriptions.
+
+---
+
+<a name="jsbridgeadd"></a>
+
+## `jsbridge:add`
+
+Add a Host App method to call from your Mini App.
+
+```bash
+minikit-cli jsbridge:add [className] [methodName] [options]
+```
+
+**Arguments**
+
+| Argument | Format | Example |
+|---|---|---|
+| `className` | PascalCase | `GPAuth`, `GPWallet` |
+| `methodName` | camelCase | `getToken`, `getBalance` |
+
+Both arguments are optional — omit either to be prompted.
+
+**Options**
+
+| Option | Alias | Description |
+|---|---|---|
+| `--cache` | `-c` | Cache the result for the session lifetime |
+
+**Examples**
+
+```bash
+minikit-cli jsbridge:add
+minikit-cli jsbridge:add GPAuth getToken --cache
+```
+
+This creates a handler in `src/bridge/handlers/` and automatically exports it.
+
+<a name="jsbridgeremove"></a>
+
+## `jsbridge:remove`
+
+Remove a previously added JS Bridge method and its generated hook.
+
+```bash
+minikit-cli jsbridge:remove [className] [methodName]
+```
+
+Both arguments are optional — omit either to pick from a list.
+
+**Examples**
+
+```bash
+minikit-cli jsbridge:remove
+minikit-cli jsbridge:remove GPAuth getToken
+```
+
+This cleans up the handler files and associated exports.
+
+<a name="i18nadd"></a>
+
+## `i18n:add`
+
+Add multi-language support with JSON-based translations.
+
+```bash
+minikit-cli i18n:add
+```
+
+Translations are stored and managed in local JSON files, which is simple and suitable for projects needing basic internationalization.
+
+<a name="snapadd"></a>
+
+## `snap:add`
+
+Add Snap Checkout (Midtrans) payment integration.
+
+```bash
+minikit-cli snap:add
+```
+
+No options or prompts — fully automatic. Generates a Snap Checkout page, registers a `/snap-checkout` route, and adds required env keys to `.env.example`.
+
+<a name="vconsoleadd"></a>
+
+## `vconsole:add`
+
+Add vConsole, an in-app debug panel.
+
+```bash
+minikit-cli vconsole:add
+```
+
+No options or prompts — fully automatic. Provides a mobile-friendly console for viewing logs and debugging the app. Active in dev mode by default.
+
+<a name="update"></a>
+
+## `update`
+
+Update the MiniKit CLI itself to the latest published version.
+
+```bash
+minikit-cli update [options]
+```
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `--check` | Report current vs. latest version without installing |
+| `--tag <tag>` | dist-tag to resolve. Defaults to `beta` for prerelease installs, `latest` for stable. |
+
+**Examples**
+
+```bash
+minikit-cli update
+minikit-cli update --check
+minikit-cli update --tag latest
+```
+
+Run `minikit-cli migrate` inside each project after updating to apply project-level migrations.
+
+<a name="migrate"></a>
+
+## `migrate`
+
+Apply version-to-version migrations to an existing project. Run after `minikit-cli update`.
+
+```bash
+minikit-cli migrate [target-version] [options]
+```
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `--to <version>` | Migrate only up to this version |
+| `--dry-run` | Show the migration plan without applying changes |
+| `--check` | Report the project's current version vs. the latest reachable version |
+
+**Examples**
+
+```bash
+minikit-cli migrate
+minikit-cli migrate --dry-run
+minikit-cli migrate --to 1.3.0
+minikit-cli migrate --check
+```
+
+<a name="docs"></a>
+
+## `docs`
+
+List or search documentation links.
+
+```bash
+minikit-cli docs [keyword]
+```
+
+**Examples**
+
+```bash
+minikit-cli docs
+minikit-cli docs jsbridge
+```
+
+Search is case-insensitive, matches document names and titles.
+
+## Getting help
+
+Every command supports `--help`:
+
+```bash
+minikit-cli --help
+minikit-cli create --help
+minikit-cli update --help
+minikit-cli migrate --help
+minikit-cli jsbridge:add --help
+minikit-cli jsbridge:remove --help
+minikit-cli snap:add --help
+minikit-cli vconsole:add --help
+minikit-cli i18n:add --help
+```