buildx-cli 1.0.9 → 1.0.11

package/README.md

@@ -6,7 +6,8 @@ A command-line interface tool for BuildX API with authentication, project manage
 
 - **🔐 Authentication Management**: Secure login/logout with token validation
 - **📁 Project Management**: List, set default, and manage multiple projects
-- **🔄 Schema Synchronization**: Generate TypeScript types from API schema
+- **🔄 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
 
@@ -48,9 +49,14 @@ yarn start --help
    npx buildx-cli projects:list
    ```
 
-4. **Sync schema:**
+4. **Pull schema:**
    ```bash
-   npx buildx-cli schema:sync --project-id <project-id>
+   npx buildx-cli schema:pull --project-id <project-id>
+   ```
+
+5. **Pull function code:**
+   ```bash
+   npx buildx-cli function:pull --project-id <project-id>
    ```
 
 ## Configuration
@@ -69,6 +75,28 @@ 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
@@ -86,82 +114,307 @@ npx buildx-cli config:clear
 
 ## Commands
 
-### Authentication Commands
+### Authentication
+
+#### `auth:login`
+Logs in with token or username/password interactively.
 
-#### Login
 ```bash
 npx buildx-cli auth:login
 ```
-Interactive login with username/password or token.
 
-#### Logout
+#### `auth:logout`
+Clears stored authentication.
+
 ```bash
 npx buildx-cli auth:logout
 ```
-Clear stored authentication.
 
-#### Check Status
+#### `auth:status`
+Shows current auth state and user details (if available).
+
 ```bash
 npx buildx-cli auth:status
 ```
-Display authentication status and user information.
 
-### Project Management Commands
+### Projects
+
+#### `projects:list`
+Lists available projects for the authenticated account.
 
-#### List Projects
 ```bash
 npx buildx-cli projects:list
 ```
-Display all available projects.
 
-#### Set Default Project
+#### `projects:set-default <project-id>`
+Sets default project used by commands when `--project-id` is not provided.
+
 ```bash
-npx buildx-cli projects:set-default <project-id>
+npx buildx-cli projects:set-default hello-world
 ```
-Set the default project for operations.
 
-#### Show Current Project
+#### `projects:current`
+Shows currently selected default project.
+
 ```bash
 npx buildx-cli projects:current
 ```
-Display the currently selected default project.
 
-### Schema Synchronization Commands
+### 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`
 
-#### Sync Schema
 ```bash
-npx buildx-cli schema:sync --project-id <project-id>
+npx buildx-cli schema:diff --project-id hello-world --target-dir ./.sandbox/buildx-cli
 ```
 
-#### Sync with Custom Output
+### 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 schema:sync --project-id <project-id> --output ./src/types/generated.ts
+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
 ```
 
-#### Sync with Custom API URL
+`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 schema:sync --project-id <project-id> --api-url https://custom-api.example.com
+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
 
-#### Setup Configuration
+#### `config:setup`
+Interactive API configuration (`endpoint`, `api key`).
+
 ```bash
 npx buildx-cli config:setup
 ```
-Interactive configuration setup.
 
-#### Show Configuration
+#### `config:show`
+Displays current resolved configuration (use this to inspect configured API endpoint).
+
 ```bash
 npx buildx-cli config:show
 ```
-Display current configuration and sources.
 
-#### Clear Configuration
+#### `config:clear`
+Clears all saved CLI configuration.
+
 ```bash
 npx buildx-cli config:clear
 ```
-Clear all stored configuration.
 
 ## Configuration Sources
 
@@ -178,6 +431,11 @@ The CLI checks for configuration in this order:
 - `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
 
@@ -186,7 +444,13 @@ 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
+- `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
 
@@ -238,8 +502,8 @@ export BUILDX_API_ENDPOINT=https://api.example.com
 export BUILDX_API_KEY=$CI_API_KEY
 export BUILDX_PROJECT_ID=$CI_PROJECT_ID
 
-# Run schema sync
-npx buildx-cli schema:sync --project-id $BUILDX_PROJECT_ID --output ./src/types/api.ts
+# Run schema pull
+npx buildx-cli schema:pull --project-id $BUILDX_PROJECT_ID --output ./src/types/api.ts
 ```
 
 ### Local Development
@@ -249,7 +513,23 @@ npx buildx-cli config:setup
 
 # Use regularly
 npx buildx-cli projects:list
-npx buildx-cli schema:sync --project-id my-project
+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
@@ -263,4 +543,4 @@ npx buildx-cli schema:sync --project-id my-project
 
 ## License
 
-MIT License - see LICENSE file for details. 
+MIT License - see LICENSE file for details.