npm package: @mapples/cli
Description: Mapples CLI
Author: Oleksandr Soloviov
Latest version: 0.0.17

# Mapples CLI

A command-line interface for managing Mapples projects, enabling developers to initialize projects, synchronize pages from the API, and manage project configurations.

## Installation

```bash
npm install -g @mapples/cli
```

Or using yarn:

```bash
yarn global add @mapples/cli
```

## Usage

### Initialize a Project

Initialize a new Mapples project with configuration:

```bash
mapples init
```

This command will:

- Prompt you for configuration values (sandbox URL, asset URL, API key, etc.)
- Create a `.mapplesrc.json` configuration file
- Update your `.gitignore` to exclude the configuration file

### Manage Pages

#### Synchronize Pages from API

Fetch and create page components from the Mapples API:

```bash
mapples pages --sync
```

This command will:

- Fetch all pages from the configured API endpoint
- Generate React components using templates
- Create page directories with the following structure:
  ```
  mapples/pages/{PageName}/
  ├── {PageName}Mapplet.tsx
  ├── {PageName}.json
  ├── _meta_{PageName}.json
  ├── index.ts
  └── .donotedit
  ```

#### Show Pages Information

Display information about all pages in a formatted table:

```bash
mapples pages --info
```

This shows:

- Page names and UUIDs
- Creation and update timestamps
- Sync status (New, Synced, Update, Error)
- Color-coded status indicators

## Configuration

The CLI uses a `.mapplesrc.json` file for configuration. Here are the available options:

```json
{
  "sandboxUrl": "https://staging.mapples.org",
  "assetUrl": "https://staging.assets.mapples.org",
  "apiKey": "your-api-key-here",
  "useExpoRouter": false,
  "pagesDir": "pages",
  "styleDir": "style",
  "assetsDir": "assets",
  "sourceDir": "mapples"
}
```

### Configuration Options

- **sandboxUrl**: The base URL for the Mapples API
- **assetUrl**: The base URL for Mapples assets
- **apiKey**: Your Mapples API key (required)
- **useExpoRouter**: Whether to use Expo Router for navigation
- **pagesDir**: Directory name for pages (default: "pages")
- **styleDir**: Directory name for styles (default: "style")
- **assetsDir**: Directory name for assets (default: "assets")
- **sourceDir**: Source directory name (default: "mapples")

## Generated Files

When synchronizing pages, the CLI generates the following files for each page:

### Component File (`{PageName}Mapplet.tsx`)

A React component that uses the `@mapples/render` package to render page content.

### Data File (`{PageName}.json`)

Contains the page data fetched from the API.

### Meta File (`_meta_{PageName}.json`)

Contains page metadata (excluding the data payload) for tracking updates.

### Index File (`index.ts`)

Exports the page component for easy importing.

### Protection File (`.donotedit`)

A marker file to prevent accidental editing of generated content.

## Development

### Prerequisites

- Node.js (v16 or higher)
- Yarn 4.10.2

### Setup

1. Clone the repository:

```bash
git clone https://github.com/mapplesorg/cli.git
cd cli
```

2. Install dependencies:

```bash
yarn install
```

3. Build the project:

```bash
yarn build
```

### Available Scripts

- `yarn build` - Build the project for development
- `yarn build:prod` - Build the project for production
- `yarn dev` - Build and watch for changes
- `yarn clean` - Remove the dist directory
- `yarn format` - Format code with Prettier
- `yarn format:check` - Check code formatting
- `yarn lint` - Run ESLint

### Publishing

The package is automatically built for production before publishing:

```bash
yarn prepublishOnly
```

## License

MIT

## Author

Oleksandr Soloviov <oleksolv@gmail.com>

## Repository

https://github.com/mapplesorg/cli