buildx-cli 1.0.10 → 1.0.11

package/dist/README.md

@@ -0,0 +1,546 @@
+# BuildX CLI
+
+A command-line interface tool for BuildX API with authentication, project management, and schema synchronization capabilities.
+
+## Features
+
+- **🔐 Authentication Management**: Secure login/logout with token validation
+- **📁 Project Management**: List, set default, and manage multiple projects
+- **🔄 Schema Synchronization**: Pull and push collections/types as code
+- **⚡ Function Synchronization**: Pull and push function source files as code
+- **⚙️ Configuration Management**: Store settings or use environment variables
+- **🎯 Interactive CLI**: User-friendly command-line interface with prompts
+
+## Installation
+
+### Using npx (Recommended)
+```bash
+npx buildx-cli --help
+```
+
+### Global Installation
+```bash
+npm install -g buildx-cli
+```
+
+### Local Development
+```bash
+git clone <repository-url>
+cd buildx-cli
+yarn install
+yarn build
+yarn start --help
+```
+
+## Quick Start
+
+1. **Configure API settings:**
+   ```bash
+   npx buildx-cli config:setup
+   ```
+
+2. **Authenticate:**
+   ```bash
+   npx buildx-cli auth:login
+   ```
+
+3. **List projects:**
+   ```bash
+   npx buildx-cli projects:list
+   ```
+
+4. **Pull schema:**
+   ```bash
+   npx buildx-cli schema:pull --project-id <project-id>
+   ```
+
+5. **Pull function code:**
+   ```bash
+   npx buildx-cli function:pull --project-id <project-id>
+   ```
+
+## Configuration
+
+### Method 1: Interactive Setup
+```bash
+npx buildx-cli config:setup
+```
+
+### Method 2: Environment Variables
+Set these environment variables or add them to a `.env` file:
+
+```bash
+BUILDX_API_ENDPOINT=https://api.example.com
+BUILDX_API_KEY=your-api-key
+BUILDX_PROJECT_ID=your-default-project-id
+```
+
+Supported aliases (auto-resolved):
+
+```bash
+NEXT_PUBLIC_API_ENDPOINT=
+NEXT_PUBLIC_API_KEY=
+NEXT_PUBLIC_BUILDX_PROJECT_ID=
+
+NEXT_PUBLIC_BUILDX_API_ENDPOINT=
+NEXT_PUBLIC_BUILDX_API_KEY=
+
+BUILDX_API_ENDPOINT=
+BUILDX_API_KEY=
+BUILDX_PROJECT_ID=
+```
+
+Resolution priority is strict-first:
+- Endpoint: `BUILDX_API_ENDPOINT` -> `NEXT_PUBLIC_BUILDX_API_ENDPOINT` -> `NEXT_PUBLIC_API_ENDPOINT`
+- API key: `BUILDX_API_KEY` -> `NEXT_PUBLIC_BUILDX_API_KEY` -> `NEXT_PUBLIC_API_KEY`
+- Project ID: `BUILDX_PROJECT_ID` -> `NEXT_PUBLIC_BUILDX_PROJECT_ID`
+
+When running `config:setup`, CLI auto-detects these values and asks for confirmation before using them.
+
+### Method 3: Command Line Options
+```bash
+npx buildx-cli config:setup --endpoint https://api.example.com --api-key your-api-key
+```
+
+### View Current Configuration
+```bash
+npx buildx-cli config:show
+```
+
+### Clear Configuration
+```bash
+npx buildx-cli config:clear
+```
+
+## Commands
+
+### Authentication
+
+#### `auth:login`
+Logs in with token or username/password interactively.
+
+```bash
+npx buildx-cli auth:login
+```
+
+#### `auth:logout`
+Clears stored authentication.
+
+```bash
+npx buildx-cli auth:logout
+```
+
+#### `auth:status`
+Shows current auth state and user details (if available).
+
+```bash
+npx buildx-cli auth:status
+```
+
+### Projects
+
+#### `projects:list`
+Lists available projects for the authenticated account.
+
+```bash
+npx buildx-cli projects:list
+```
+
+#### `projects:set-default <project-id>`
+Sets default project used by commands when `--project-id` is not provided.
+
+```bash
+npx buildx-cli projects:set-default hello-world
+```
+
+#### `projects:current`
+Shows currently selected default project.
+
+```bash
+npx buildx-cli projects:current
+```
+
+### Schema Commands
+
+#### `schema:pull`
+Pulls schema artifacts from remote and writes local files.
+
+Writes:
+- `types.ts`
+- `collections.json` (unless `--skip-collections-code`)
+- `collections.manifest.json`
+
+Key options:
+- `-p, --project-id <id>`: project to sync from
+- `-t, --target-dir <path>`: base output directory (recommended)
+- `-o, --output <path>`: custom types path (when no `--target-dir`)
+- `--collections-file <path>`: custom collections JSON path (when no `--target-dir`)
+- `--filter <pattern...>`: include only matching collection IDs
+- `--include-buildx`: include `buildx_*` collections
+- `--skip-collections-code`: skip collections JSON/manifest output
+- `--no-annotate-types`: disable `@bx.*` annotations injection into pulled `types.ts`
+- `--dry-run`: print full file content previews without writing files
+- `-f, --force`: overwrite even if local file drift is detected
+
+```bash
+npx buildx-cli schema:pull --project-id hello-world --target-dir ./.sandbox/buildx-cli
+npx buildx-cli schema:pull --project-id hello-world --dry-run
+```
+
+`schema:sync` is still available as a compatibility alias (deprecated).
+
+#### `schema:push`
+Pushes local `collections.json` back to remote project.
+
+Reads:
+- `collections.json`
+- `collections.manifest.json` (for drift checks)
+
+Behavior:
+- validates minimum shape (`collection_id`, `form_schema`)
+- compares local checksum vs remote checksum
+- skips remote-drift conflicts unless `--force`
+
+Key options:
+- `-p, --project-id <id>`
+- `-t, --target-dir <path>`
+- `--collections-file <path>` (when no `--target-dir`)
+- `--filter <pattern...>`
+- `--dry-run`
+- `-f, --force`
+
+```bash
+npx buildx-cli schema:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run
+```
+
+#### `schema:types:convert`
+Converts a local `types.ts` file into collections JSON first, so you can review before push.
+
+Reads:
+- `types.ts` (or `--types-file`)
+- base `collections.json` to preserve metadata (required by default)
+
+Writes:
+- `collections.json` (or `--collections-file`)
+
+Key options:
+- `-t, --target-dir <path>`
+- `--types-file <path>`
+- `--collections-file <path>`
+- `--base-collections-file <path>`
+- `--no-allow-lossy` (strict mode: require base metadata file)
+- `--filter <pattern...>`
+- `--dry-run`
+
+Field annotations (JSDoc in `types.ts`) are supported:
+- `@bx.title <text>`
+- `@bx.description <text>`
+- `@bx.required` or `@bx.required false`
+- `@bx.ref <collection_id_or_enum_key>`
+- `@bx.choices value1:Label 1|value2:Label 2` (for `Choices`/`MultipleChoices`)
+
+Example:
+```ts
+export type Employees = {
+  /** @bx.title Employment status @bx.choices active:Active|on_leave:On Leave */
+  status?: BxChoices;
+  /** @bx.required */
+  employee_id?: BxText;
+  /** @bx.ref departments @bx.title Department */
+  department?: Partial<Departments> | BxDataObject;
+};
+```
+
+```bash
+npx buildx-cli schema:types:convert --target-dir ./.sandbox/buildx-cli --dry-run
+npx buildx-cli schema:types:convert --target-dir ./.sandbox/buildx-cli
+npx buildx-cli schema:push --collections-file ./.sandbox/buildx-cli/collections.json --project-id hello-world --dry-run
+```
+
+#### `schema:list`
+Lists remote collections.
+
+Key options:
+- `-p, --project-id <id>`
+- `--filter <pattern...>`
+- `--include-buildx`
+
+```bash
+npx buildx-cli schema:list --project-id hello-world --filter "user*"
+```
+
+#### `schema:diff`
+Diffs local collections against remote by `collection_id`.
+
+Reads:
+- local `collections.json`
+
+Output markers:
+- `= same`
+- `~ changed`
+- `+ local-only`
+- `- remote-only`
+
+Key options:
+- `-p, --project-id <id>`
+- `-t, --target-dir <path>`
+- `--collections-file <path>` (when no `--target-dir`)
+- `--filter <pattern...>`
+- `--include-buildx`
+
+```bash
+npx buildx-cli schema:diff --project-id hello-world --target-dir ./.sandbox/buildx-cli
+```
+
+### Function Commands
+
+#### `function:pull`
+Pulls function context schema and function source code from remote.
+
+Writes:
+- `function-context.d.ts`
+- `functions/*.ts`
+- `functions/functions.manifest.json`
+
+Behavior:
+- writes a compact `function-context.d.ts` by default (use `--full-context` to keep full remote schema)
+- preserves remote function code as-is by default (safe with existing runtime)
+- optional `--module-wrap` can normalize arrow-function code into module format (`export default`) for local tooling
+- skips overwriting local edited files unless `--force`
+- supports dry-run file content previews
+
+Key options:
+- `-p, --project-id <id>`
+- `-t, --target-dir <path>`
+- `--context-output <path>` (when no `--target-dir`)
+- `--functions-dir <path>` (when no `--target-dir`)
+- `--filter <pattern...>`
+- `--full-context`
+- `--module-wrap`
+- `--no-validate-code`
+- `--no-lint`
+- `--dry-run`
+- `-f, --force`
+
+```bash
+npx buildx-cli function:pull --project-id hello-world --target-dir ./.sandbox/buildx-cli
+npx buildx-cli function:pull --project-id hello-world --dry-run
+```
+
+`function:sync` is still available as a compatibility alias (deprecated).
+
+#### `function:push`
+Pushes local function source files back to remote.
+
+Reads:
+- `functions/*.ts`
+- `functions/functions.manifest.json`
+
+Behavior:
+- checks remote drift against manifest baseline
+- validates local function code compatibility before push (can bypass via `--no-validate-code`)
+- runs basic syntax lint before push (can bypass via `--no-lint`)
+- skips conflicts unless `--force`
+
+Key options:
+- `-p, --project-id <id>`
+- `-t, --target-dir <path>`
+- `--functions-dir <path>` (when no `--target-dir`)
+- `-n, --name <function-name>` for a single function
+- `--filter <pattern...>`
+- `--no-validate-code`
+- `--no-lint`
+- `--dry-run`
+- `-f, --force`
+
+```bash
+npx buildx-cli function:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run
+```
+
+#### `function:list`
+Lists remote function names.
+
+Key options:
+- `-p, --project-id <id>`
+- `--filter <pattern...>`
+
+```bash
+npx buildx-cli function:list --project-id hello-world --filter "send*"
+```
+
+#### `function:diff`
+Diffs local function sources against remote.
+
+Reads:
+- local `functions/*.ts`
+- `functions/functions.manifest.json`
+
+Output markers:
+- `= same`
+- `~ changed`
+- `+ local-missing`
+- `- remote-missing`
+- `! remote-drift`
+
+Key options:
+- `-p, --project-id <id>`
+- `-t, --target-dir <path>`
+- `--functions-dir <path>` (when no `--target-dir`)
+- `-n, --name <function-name>`
+- `--filter <pattern...>`
+
+```bash
+npx buildx-cli function:diff --project-id hello-world --target-dir ./.sandbox/buildx-cli
+```
+
+### Configuration Commands
+
+#### `config:setup`
+Interactive API configuration (`endpoint`, `api key`).
+
+```bash
+npx buildx-cli config:setup
+```
+
+#### `config:show`
+Displays current resolved configuration (use this to inspect configured API endpoint).
+
+```bash
+npx buildx-cli config:show
+```
+
+#### `config:clear`
+Clears all saved CLI configuration.
+
+```bash
+npx buildx-cli config:clear
+```
+
+## Configuration Sources
+
+The CLI checks for configuration in this order:
+
+1. **Stored Configuration** (via `config:setup`)
+2. **Environment Variables** (`BUILDX_API_ENDPOINT`, `BUILDX_API_KEY`)
+3. **`.env` File** (in current directory)
+
+### Configuration File Location
+- **Global config**: `~/.config/buildx-cli-nodejs/config.json`
+
+### Environment Variables
+- `BUILDX_API_ENDPOINT` - Your API endpoint URL
+- `BUILDX_API_KEY` - Your API key
+- `BUILDX_PROJECT_ID` - Default project ID (optional)
+- `NEXT_PUBLIC_BUILDX_API_ENDPOINT` - Alias for API endpoint
+- `NEXT_PUBLIC_API_ENDPOINT` - Alias for API endpoint
+- `NEXT_PUBLIC_BUILDX_API_KEY` - Alias for API key
+- `NEXT_PUBLIC_API_KEY` - Alias for API key
+- `NEXT_PUBLIC_BUILDX_PROJECT_ID` - Alias for default project ID
+
+## API Endpoints
+
+The CLI interacts with the following API endpoints:
+
+- `POST /auth/login` - User authentication
+- `GET /auth/me` - Get current user info
+- `GET /projects` - List user projects
+- `GET /project/:project_id/collections/schema` - Fetch project schema types
+- `GET /project/:project_id/collections` - Fetch collections as code
+- `POST /project/:project_id/collections` - Upsert collection
+- `GET /project/:project_id/functions/context/schema/info` - Fetch function context schema info
+- `GET /project/:project_id/functions` - List functions
+- `GET /project/:project_id/functions/:function_name` - Fetch function source
+- `POST /project/:project_id/functions/:function_name` - Upsert function source
+
+## Development
+
+### Project Structure
+
+```
+src/
+├── commands/          # CLI commands
+│   ├── auth/         # Authentication commands
+│   ├── config/       # Configuration commands
+│   ├── projects/     # Project management commands
+│   └── sync.ts       # Schema synchronization
+├── services/          # Business logic services
+├── types/            # TypeScript type definitions
+├── utils/            # Utility functions
+├── config/           # Configuration management
+└── index.ts          # Main entry point
+```
+
+### Available Scripts
+
+```bash
+yarn build          # Build the project
+yarn dev            # Run in development mode
+yarn start          # Run built version
+yarn test           # Run tests
+yarn lint           # Run linter
+yarn format         # Format code
+```
+
+### Building
+
+```bash
+yarn build
+```
+
+### Development Mode
+
+```bash
+yarn dev
+```
+
+## Examples
+
+### CI/CD Pipeline
+```bash
+# Set environment variables
+export BUILDX_API_ENDPOINT=https://api.example.com
+export BUILDX_API_KEY=$CI_API_KEY
+export BUILDX_PROJECT_ID=$CI_PROJECT_ID
+
+# Run schema pull
+npx buildx-cli schema:pull --project-id $BUILDX_PROJECT_ID --output ./src/types/api.ts
+```
+
+### Local Development
+```bash
+# Setup once
+npx buildx-cli config:setup
+
+# Use regularly
+npx buildx-cli projects:list
+npx buildx-cli schema:pull --project-id my-project
+npx buildx-cli function:pull --project-id my-project
+```
+
+### Monorepo Local Shortcuts (No Publish)
+From monorepo root:
+
+```bash
+yarn cli:build
+yarn cli --help
+```
+
+Isolated test output:
+
+```bash
+yarn cli -- schema:pull --project-id my-project --target-dir ./.sandbox/buildx-cli
+yarn cli -- function:pull --project-id my-project --target-dir ./.sandbox/buildx-cli
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite
+6. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.