@embeddables/cli 0.4.2 → 0.4.4

package/README.md

@@ -1,70 +1,168 @@
-# Embeddables CLI (development)
+# Embeddables CLI
 
-This repo is the source for **@embeddables/cli** — the CLI for authoring and managing Embeddables locally with TypeScript/TSX. If you only want to _use_ the CLI, see the [package on npm](https://www.npmjs.com/package/@embeddables/cli) or the [user-facing README](./package-readme.md) (same content as the npm package page).
+A CLI for authoring and managing Embeddables locally using TypeScript/TSX.
 
-## Prerequisites
+## Features
+
+- **Pull** existing Embeddables from the cloud and reverse-compile to TSX
+- **Build** TSX pages into the canonical Embeddable JSON format
+- **Save** compiled embeddables back to the cloud (with optional version labels and branches)
+- **Dev** mode with hot reload and proxy to a live Engine instance
+- Full **TypeScript support** with autocomplete for all component primitives
+
+## Requirements
 
 - Node.js >= 18.0.0
 
-## Setup
+## Installation
+
+Install the CLI globally:
 
 ```bash
-git clone <this-repo>
-cd embeddables-cli
-npm install
+npm install -g @embeddables/cli
 ```
 
-## Scripts
+## Quick Start
 
-| Script                  | Description                   |
-| ----------------------- | ----------------------------- |
-| `npm run build`         | Compile TypeScript to `dist/` |
-| `npm run build:watch`   | Watch and recompile on change |
-| `npm test`              | Run tests (Vitest)            |
-| `npm run test:watch`    | Run tests in watch mode       |
-| `npm run test:coverage` | Coverage report               |
-| `npm run lint`          | ESLint                        |
-| `npm run format`        | Prettier (write)              |
-| `npm run format:check`  | Prettier (check only)         |
-| `npm run build-workbench` | Build Workbench bundle for CDN (e.g. `-- --out workbench-worker`) |
+```bash
+# Login to your Embeddables account (this applies gobally)
+embeddables login
 
-## Local testing
+# Initialize a new project, from within a new folder (will ask for your Embeddables project ID if not skipped)
+embeddables init
 
-After building, link the CLI so you can run `embeddables` from another project:
+# Pull an embeddable (shows a list to choose from when logged in)
+embeddables pull
 
-```bash
-npm run build
-npm link
+# Start dev server with hot reload (proxies to production engine by default)
+embeddables dev
 ```
 
-Then in a project that uses the CLI (e.g. an embeddables app), run `embeddables <command>` — it will use your linked build. Unlink with `npm unlink -g @embeddables/cli` when done.
-
-You can also run the CLI without installing, from this repo:
+This creates the following structure in your repo:
 
-```bash
-npx tsx src/cli.ts dev
-# or
-npx tsx src/cli.ts build -i <embeddable-id>
 ```
+embeddables/
+  <embeddable-id>/
+    pages/               # TSX page files
+    styles/              # CSS styles
+    computed-fields/     # Custom computed field logic
+    actions/             # Data output actions
+    config.json          # Embeddable configuration
+    .generated/          # Compiled JSON output
+```
+
+## Commands
+
+### `embeddables init`
+
+Initialize a new Embeddables project. Creates `embeddables.json`, `.gitignore`, `.types/` (type stubs), `tsconfig.json` (if missing), and an `embeddables/` directory.
+
+If you're logged in and don't use `--yes`, you'll see an interactive list of your projects to choose from. Otherwise you can enter a project ID manually or skip.
+
+Options:
+
+- `-p, --project-id <id>`: Embeddables project ID (shows list if logged in and not using `--yes`)
+- `-y, --yes`: Skip prompts and use defaults
+
+The project ID is stored in `embeddables.json` and enables interactive embeddable selection when running `embeddables pull` and `embeddables save`.
+
+### `embeddables login`
+
+Authenticate with your Embeddables account.
+
+### `embeddables logout`
+
+Clear stored authentication.
+
+### `embeddables pull`
+
+Fetch an embeddable from the cloud and reverse-compile it into local TSX files.
 
-## Project structure
+If you're logged in and run `embeddables pull` without `--id`:
 
-- **`src/cli.ts`** — Commander setup and command registration
-- **`src/commands/`** — Implementations for `init`, `login`, `logout`, `pull`, `branch`, `build`, `save`, `dev`
-- **`src/compiler/`** — TSX → JSON compile and JSON → TSX reverse-compile
-- **`src/config/`** — `embeddables.json` and project config
-- **`src/auth/`** — Login/logout and token storage
-- **`src/prompts/`** — Interactive prompts (projects, embeddables, branches)
-- **`src/proxy/`** — Dev server and engine proxy
-- **`src/components/`** — React primitives exported as `@embeddables/cli/components`
-- **`bin/embeddables.mjs`** — Entry script that runs `dist/cli.js`
-- **`scripts/run-build-workbench.ts`** — Entry for `npm run build-workbench` (builds Workbench from `src/workbench/` for CDN deploy)
-- **`tests/`** — Unit and integration tests (Vitest)
+1. If no project is configured, you'll be prompted to select one (saved to `embeddables.json`)
+2. Then you'll see an interactive list of embeddables to choose from
 
-## Publishing
+Options:
 
-The user-facing README is in **`package-readme.md`**. It is swapped in as `README.md` during `npm pack` / `npm publish` via `prepack`/`postpack` scripts so the npm package shows the right docs. Do not remove those scripts.
+- `-i, --id <id>`: Embeddable ID to pull (skips interactive selection)
+- `-o, --out <path>`: Output path for the compiled JSON (default: `embeddables/<id>/.generated/embeddable.json`)
+- `-b, --branch <branch_id>`: Pull a specific branch version
+- `-f, --fix`: Remove components with missing required props instead of erroring
+
+### `embeddables branch`
+
+Switch to a different branch of a local embeddable. Shows an interactive list of branches to choose from, then pulls that branch. Requires login.
+
+Options:
+
+- `-i, --id <id>`: Embeddable ID (will prompt from local embeddables if not provided)
+
+### `embeddables build`
+
+Compile TSX pages into the canonical JSON format. You usually don't need to run this yourself: `embeddables save` builds automatically before uploading (unless you pass `--skip-build`). Use `build` when you only want to compile (e.g. to inspect `.generated/embeddable.json`) or when you run build and save separately (e.g. `build` then `save --skip-build`).
+
+Options:
+
+- `-i, --id <id>` (required): Embeddable ID
+- `-p, --pages <glob>`: Custom pages glob pattern (default: `embeddables/<id>/pages/**/*.page.tsx`)
+- `-o, --out <path>`: Custom output path (default: `embeddables/<id>/.generated/embeddable.json`)
+- `--pageKeyFrom <mode>`: How to derive page keys: `filename` or `export` (default: `filename`)
+
+### `embeddables save`
+
+Build the embeddable (unless `--skip-build` is set) and save it to the cloud. Uses the version in `config.json` or `.generated/` for optimistic concurrency; prompts to force-save if the server has a newer version. Requires login.
+
+Options:
+
+- `-i, --id <id>`: Embeddable ID (will prompt from local embeddables if not provided)
+- `-l, --label <label>`: Human-readable label for this version
+- `-b, --branch <branch_id>`: Branch ID to save to
+- `-s, --skip-build`: Skip the build step and use existing compiled JSON from `.generated/embeddable.json`
+- `--from-version <number>`: Base version number (auto-detected from local config/files if not provided)
+
+### `embeddables dev`
+
+Start a dev server with hot reload. Proxies to the Engine; by default uses production (`https://engine.embeddables.com`). Use `--local` to point to a local engine.
+
+Options:
+
+- `-i, --id <id>`: Embeddable ID (will prompt if not provided)
+- `-p, --pages <glob>`: Custom pages glob
+- `-o, --out <path>`: Output path for compiled JSON
+- `-L, --local`: Use local engine (`http://localhost:8787`) instead of production
+- `-e, --engine <url>`: Engine origin (default: `https://engine.embeddables.com`; overridden by `--local`)
+- `--port <n>`: Dev proxy port (default: `3000`)
+- `--overrideRoute <path>`: Route to override in proxy, exact match (default: `/init`)
+- `--pageKeyFrom <mode>`: `filename` or `export` (default: `filename`)
+
+## Authoring with TypeScript
+
+Import component primitives for full autocomplete:
+
+```tsx
+import { Container, InputBox, PlainText, CustomButton } from '@embeddables/cli/components'
+
+export default function MyPage() {
+  return (
+    <Container id="main" key="main">
+      <PlainText id="title" key="title" text="Welcome!" />
+      <InputBox
+        id="email"
+        key="email"
+        input_type="email"
+        label="Email"
+        placeholder="you@example.com"
+        isRequired
+      />
+      <CustomButton id="submit" key="submit" text="Continue" action="next-page" />
+    </Container>
+  )
+}
+```
 
-## User documentation
+Package exports:
 
-Full command reference, installation, and usage for people who install the package: **[package-readme.md](./package-readme.md)**.
+- `@embeddables/cli` — CLI entry (binary)
+- `@embeddables/cli/components` — React component primitives for authoring
+- `@embeddables/cli/types` — Type definitions for embeddable JSON

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embeddables/cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "bin": {
     "embeddables": "./bin/embeddables.mjs"
@@ -42,7 +42,9 @@
     "test": "vitest",
     "test:watch": "vitest --watch",
     "test:coverage": "vitest --coverage",
-    "test:verbose": "vitest --reporter verbose"
+    "test:verbose": "vitest --reporter verbose",
+    "prepack": "node scripts/readme-swap.cjs prepack",
+    "postpack": "node scripts/readme-swap.cjs postpack"
   },
   "dependencies": {
     "@babel/generator": "^7.28.6",