@embeddables/cli 0.4.0 → 0.4.1

package/README.md

@@ -1,146 +1,68 @@
-# Embeddables CLI
+# Embeddables CLI (development)
 
-A CLI for authoring and managing Embeddables locally using TypeScript/TSX.
+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).
 
-## Features
+## Prerequisites
 
-- **Pull** existing Embeddables from the cloud and reverse-compile to TSX
-- **Build** TSX pages into the canonical Embeddable JSON format
-- **Dev** mode with hot reload and proxy to a live Engine instance
-- Full **TypeScript support** with autocomplete for all component primitives
+- Node.js >= 18.0.0
 
-## Installation
-
-Install the CLI globally:
-
-```bash
-npm install -g @embeddables/cli
-```
-
-## Quick Start
+## Setup
 
 ```bash
-# Initialize a new project (will ask for your Embeddables project ID)
-embeddables init
-
-# Install dependencies
+git clone <this-repo>
+cd embeddables-cli
 npm install
-
-# Login to your Embeddables account
-embeddables login
-
-# Pull an embeddable (shows a list to choose from)
-embeddables pull
-
-# Start dev server with hot reload
-embeddables dev
 ```
 
-This creates the following structure in your repo:
-
-```
-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 `package.json`, `embeddables.json`, `.gitignore`, and an `embeddables/` directory.
-
-If you're logged in, you'll see an interactive list of your projects to choose from. Otherwise, you can enter a project ID manually or skip.
-
-Options:
-- `--name <name>`: Project name (prompts if not provided)
-- `--project-id <id>`: Embeddables project ID (shows list if logged in)
-- `-y, --yes`: Skip prompts and use defaults
-
-The project ID is stored in `embeddables.json` and enables interactive embeddable selection when running `embeddables pull`.
-
-### `embeddables login`
-Authenticate with your Embeddables account.
+## Scripts
 
-### `embeddables logout`
-Clear stored authentication.
+| 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)         |
 
-### `embeddables pull`
-Fetch an embeddable from the cloud and reverse-compile it into local TSX files.
+## Local testing
 
-If you're logged in and run `embeddables pull` without arguments:
-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
+After building, link the CLI so you can run `embeddables` from another project:
 
-Options:
-- `--id <id>`: Embeddable ID to pull (skips interactive selection)
-- `--branch <branch_id>`: Pull a specific branch version
-- `--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.
-
-Options:
-- `--id <id>`: Embeddable ID (will prompt from local embeddables if not provided)
-
-### `embeddables build --id <id>`
-Compile TSX pages into the canonical JSON format.
-
-Options:
-- `--id <id>` (required): Embeddable ID
-- `--pages <glob>`: Custom pages glob pattern
-- `--out <path>`: Custom output path
-
-### `embeddables dev`
-Start a dev server with hot reload.
-
-Options:
-- `--id <id>`: Embeddable ID (will prompt if not provided)
-- `--engine <url>`: Engine origin (default: `http://localhost:8787`)
-- `--remote`: Use production engine (`https://engine.embeddables.com`)
-- `--port <n>`: Dev proxy port (default: `3000`)
-
-## Authoring with TypeScript
+```bash
+npm run build
+npm link
+```
 
-Import component primitives for full autocomplete:
+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.
 
-```tsx
-import { Container, InputBox, PlainText, CustomButton } from '@embeddables/cli/components'
+You can also run the CLI without installing, from this repo:
 
-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>
-  )
-}
+```bash
+npx tsx src/cli.ts dev
+# or
+npx tsx src/cli.ts build -i <embeddable-id>
 ```
 
-## Development (Contributing)
+## Project structure
 
-```bash
-# Install dependencies
-npm install
+- **`src/cli.ts`** — Commander setup and command registration
+- **`src/commands/`** — Implementations for `init`, `login`, `logout`, `pull`, `branch`, `build`, `save`, `dev`, `build-workbench`
+- **`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`
+- **`tests/`** — Unit and integration tests (Vitest)
 
-# Build the CLI
-npm run build
+## Publishing
 
-# Link for local testing
-npm link
+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.
 
-# Run tests
-npm test
-```
+## User documentation
+
+Full command reference, installation, and usage for people who install the package: **[package-readme.md](./package-readme.md)**.

package/dist/cli.js

@@ -23,27 +23,27 @@ program.name('embeddables').description('Embeddables CLI').version('0.1.0');
 program
     .command('init')
     .description('Initialize a new Embeddables project')
-    .option('--project-id <id>', 'Embeddables project ID')
+    .option('-p, --project-id <id>', 'Embeddables project ID')
     .option('-y, --yes', 'Skip prompts and use defaults')
     .action(async (opts) => {
     await runInit({ projectId: opts.projectId, yes: opts.yes });
 });
 program
     .command('build')
-    .requiredOption('--id <id>', 'Embeddable ID')
-    .option('--pages <glob>', 'Pages glob')
-    .option('--out <path>', 'Output json path')
+    .requiredOption('-i, --id <id>', 'Embeddable ID')
+    .option('-p, --pages <glob>', 'Pages glob')
+    .option('-o, --out <path>', 'Output json path')
     .option('--pageKeyFrom <mode>', 'filename|export', 'filename')
     .action(async (opts) => {
     await runBuild(opts);
 });
 program
     .command('dev')
-    .option('--id <id>', 'Embeddable ID (will prompt if not provided)')
-    .option('--pages <glob>', 'Pages glob')
-    .option('--out <path>', 'Output json path')
-    .option('--local', 'Use local engine (http://localhost:8787)')
-    .option('--engine <url>', 'Engine origin', 'https://engine.embeddables.com')
+    .option('-i, --id <id>', 'Embeddable ID (will prompt if not provided)')
+    .option('-p, --pages <glob>', 'Pages glob')
+    .option('-o, --out <path>', 'Output json path')
+    .option('-L, --local', 'Use local engine (http://localhost:8787)')
+    .option('-e, --engine <url>', 'Engine origin', 'https://engine.embeddables.com')
     .option('--port <n>', 'Dev proxy port', '3000')
     .option('--overrideRoute <path>', 'Route to override in proxy (exact match, no wildcards yet)', '/init')
     .option('--pageKeyFrom <mode>', 'filename|export', 'filename')
@@ -69,20 +69,20 @@ program
 program
     .command('pull')
     .description('Pull an embeddable from the cloud')
-    .option('--id <id>', 'Embeddable ID to pull (interactive selection if not provided)')
-    .option('--out <path>', 'Output json path')
-    .option('--branch <branch_id>', 'Embeddable branch ID')
-    .option('--fix', 'Fix by removing components missing required props (warn instead of error)')
+    .option('-i, --id <id>', 'Embeddable ID to pull (interactive selection if not provided)')
+    .option('-o, --out <path>', 'Output json path')
+    .option('-b, --branch <branch_id>', 'Embeddable branch ID')
+    .option('-f, --fix', 'Fix by removing components missing required props (warn instead of error)')
     .action(async (opts) => {
     await runPull(opts);
 });
 program
     .command('save')
     .description('Build and save an embeddable to the cloud')
-    .option('--id <id>', 'Embeddable ID (will prompt if not provided)')
-    .option('--label <label>', 'Human-readable label for this version')
-    .option('--branch <branch_id>', 'Branch ID to save to')
-    .option('--skip-build', 'Skip the build step and use existing compiled JSON')
+    .option('-i, --id <id>', 'Embeddable ID (will prompt if not provided)')
+    .option('-l, --label <label>', 'Human-readable label for this version')
+    .option('-b, --branch <branch_id>', 'Branch ID to save to')
+    .option('-s, --skip-build', 'Skip the build step and use existing compiled JSON')
     .option('--from-version <number>', 'Base version number (auto-detected from local files if not provided)')
     .action(async (opts) => {
     await runSave({
@@ -96,14 +96,14 @@ program
 program
     .command('branch')
     .description('Switch to a different branch of an embeddable')
-    .option('--id <id>', 'Embeddable ID (will prompt if not provided)')
+    .option('-i, --id <id>', 'Embeddable ID (will prompt if not provided)')
     .action(async (opts) => {
     await runBranch(opts);
 });
 program
     .command('build-workbench')
     .description('Build Workbench for CDN deployment')
-    .option('--out <path>', 'Output directory', 'dist/workbench')
+    .option('-o, --out <path>', 'Output directory', 'dist/workbench')
     .option('--no-minify', 'Disable minification (for debugging)')
     .action(async (opts) => {
     await runBuildWorkbench(opts);

package/dist/commands/save.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AA+FA,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,iBAoPA"}
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AAoJA,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,iBAoBA"}

package/dist/commands/save.js

@@ -8,6 +8,48 @@ import { compileAllPages } from '../compiler/index.js';
 import { formatError } from '../compiler/errors.js';
 import { promptForLocalEmbeddable, promptForProject } from '../prompts/index.js';
 import { WEB_APP_BASE_URL } from '../constants.js';
+/** Error with optional gray detail line (hint/next step) for the user. */
+class SaveError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.detail = detail;
+        this.name = 'SaveError';
+    }
+}
+/**
+ * Parse response body as JSON. Returns null if body is not valid JSON (e.g. HTML error page).
+ */
+async function safeParseJson(response) {
+    try {
+        const data = await response.json();
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function isSaveErrorResponse(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'error' in value &&
+        typeof value.error === 'string');
+}
+function isSaveConflictResponse(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'latestVersionNumber' in value &&
+        'yourVersionNumber' in value &&
+        typeof value.latestVersionNumber === 'number' &&
+        typeof value.yourVersionNumber === 'number');
+}
+function isSaveResponse(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.success === true &&
+        typeof value.data === 'object' &&
+        typeof value.data?.newVersionNumber === 'number');
+}
 /**
  * Read `_version` from config.json for the given embeddable.
  */
@@ -67,6 +109,30 @@ function getLatestVersionFromFiles(generatedDir) {
     return maxVersion;
 }
 export async function runSave(opts) {
+    try {
+        await runSaveInner(opts);
+    }
+    catch (error) {
+        if (error instanceof SaveError) {
+            console.error(pc.red(`Save failed: ${error.message}`));
+            if (error.detail) {
+                console.log(pc.gray(error.detail));
+            }
+        }
+        else if (error instanceof Error) {
+            console.error(pc.red(`Save failed: ${error.message}`));
+        }
+        else {
+            console.error(pc.red('Save failed with an unexpected error.'));
+        }
+        process.exit(1);
+        // Rethrow only when exit was mocked to throw (e.g. in tests expecting rejection)
+        if (error instanceof Error && error.message === 'exit') {
+            throw error;
+        }
+    }
+}
+async function runSaveInner(opts) {
     // 1. Check login
     if (!isLoggedIn()) {
         console.error(pc.red('Not logged in.'));
@@ -195,75 +261,106 @@ export async function runSave(opts) {
         Authorization: `Bearer ${accessToken}`,
         'Content-Type': 'application/json',
     };
+    let response;
     try {
-        const response = await fetch(url, {
+        response = await fetch(url, {
             method: 'POST',
             headers,
             body: JSON.stringify(body),
         });
-        if (response.status === 409) {
-            const conflictResult = (await response.json());
-            console.log('');
-            console.warn(pc.yellow(`⚠ Version conflict: the server has version ${conflictResult.latestVersionNumber}, but you are saving from version ${conflictResult.yourVersionNumber}.`));
-            const { forceSave } = await prompts({
-                type: 'confirm',
-                name: 'forceSave',
-                message: 'A newer version exists on the server. Save anyway?',
-                initial: false,
-            }, {
-                onCancel: () => {
-                    process.exit(1);
-                },
-            });
-            if (!forceSave) {
-                console.log(pc.gray('Save cancelled.'));
-                process.exit(0);
-            }
-            // Retry with force flag
-            console.log(pc.cyan('Retrying save with force...'));
-            const forceResponse = await fetch(url, {
+    }
+    catch (networkError) {
+        const message = networkError instanceof Error ? networkError.message : 'Network request failed';
+        if (message.includes('fetch') ||
+            message.includes('ECONNREFUSED') ||
+            message.includes('ETIMEDOUT') ||
+            message.includes('ENOTFOUND') ||
+            message.includes('network')) {
+            throw new SaveError(`Could not reach the server (${message}).`, `Check your connection and that the base URL is correct (currently ${WEB_APP_BASE_URL}).`);
+        }
+        throw new SaveError(`Network error: ${message}`, 'Check your network and firewall settings.');
+    }
+    if (response.status === 404) {
+        throw new SaveError('Save endpoint not found. The server may not support this feature or the URL may be incorrect.', `The request was sent to ${WEB_APP_BASE_URL}. If you use a custom deployment, ensure the save-version API is available there.`);
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new SaveError('Not authorized.', 'Run "embeddables login" to re-authenticate.');
+    }
+    if (response.status >= 500) {
+        throw new SaveError(`Server error (HTTP ${response.status}). Please try again later.`, 'If this keeps happening, try again later or contact support.');
+    }
+    if (response.status === 409) {
+        const conflictResult = await safeParseJson(response);
+        if (!conflictResult || !isSaveConflictResponse(conflictResult)) {
+            throw new SaveError(`Version conflict but invalid response (HTTP ${response.status}).`, 'Try saving again; if it persists, the server may be misconfigured.');
+        }
+        console.log('');
+        console.warn(pc.yellow(`⚠ Version conflict: the server has version ${conflictResult.latestVersionNumber}, but you are saving from version ${conflictResult.yourVersionNumber}.`));
+        const { forceSave } = await prompts({
+            type: 'confirm',
+            name: 'forceSave',
+            message: 'A newer version exists on the server. Save anyway?',
+            initial: false,
+        }, {
+            onCancel: () => {
+                process.exit(1);
+            },
+        });
+        if (!forceSave) {
+            console.log(pc.gray('Save cancelled.'));
+            process.exit(0);
+        }
+        // Retry with force flag
+        console.log(pc.cyan('Retrying save with force...'));
+        let forceResponse;
+        try {
+            forceResponse = await fetch(url, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({ ...body, force: true }),
             });
-            const forceResult = (await forceResponse.json());
-            if (!forceResponse.ok) {
-                const errorResult = forceResult;
-                throw new Error(errorResult.error || `HTTP ${forceResponse.status}`);
-            }
-            const successResult = forceResult;
-            const { newVersionNumber } = successResult.data;
-            console.log(pc.green(`✓ Saved as version ${newVersionNumber}`));
-            setVersionInConfig(embeddableId, newVersionNumber);
-            const versionedPath = path.join(generatedDir, `embeddable-v${newVersionNumber}.json`);
-            fs.mkdirSync(generatedDir, { recursive: true });
-            fs.writeFileSync(versionedPath, jsonContent, 'utf8');
-            console.log(pc.cyan(`✓ Saved version file to ${versionedPath}`));
-            return;
         }
-        const result = (await response.json());
-        if (!response.ok) {
-            const errorResult = result;
-            throw new Error(errorResult.error || `HTTP ${response.status}`);
+        catch (forceNetworkError) {
+            const message = forceNetworkError instanceof Error ? forceNetworkError.message : 'Network request failed';
+            throw new SaveError(`Retry failed: ${message}`, 'The initial save hit a version conflict; the force-save retry could not reach the server.');
+        }
+        if (forceResponse.status === 404) {
+            throw new SaveError('Save endpoint not found. The server may not support this feature or the URL may be incorrect.', `The request was sent to ${WEB_APP_BASE_URL}. If you use a custom deployment, ensure the save-version API is available there.`);
+        }
+        const forceResult = await safeParseJson(forceResponse);
+        if (!forceResponse.ok) {
+            const errorMessage = forceResult && isSaveErrorResponse(forceResult)
+                ? forceResult.error
+                : `HTTP ${forceResponse.status}`;
+            throw new SaveError(errorMessage, 'If the problem persists, run "embeddables login" or try again later.');
+        }
+        if (!forceResult || !isSaveResponse(forceResult)) {
+            throw new SaveError(`Invalid response from server (HTTP ${forceResponse.status}).`, 'The server returned an unexpected format. Try again or contact support if it persists.');
         }
-        const successResult = result;
-        const { newVersionNumber } = successResult.data;
+        const { newVersionNumber } = forceResult.data;
         console.log(pc.green(`✓ Saved as version ${newVersionNumber}`));
-        // Update _version in config.json so future saves know the base version
         setVersionInConfig(embeddableId, newVersionNumber);
-        // Also save the versioned file to .generated/ as a snapshot
         const versionedPath = path.join(generatedDir, `embeddable-v${newVersionNumber}.json`);
         fs.mkdirSync(generatedDir, { recursive: true });
         fs.writeFileSync(versionedPath, jsonContent, 'utf8');
         console.log(pc.cyan(`✓ Saved version file to ${versionedPath}`));
+        return;
     }
-    catch (error) {
-        if (error instanceof Error) {
-            console.error(pc.red(`Save failed: ${error.message}`));
-        }
-        else {
-            console.error(pc.red('Save failed with an unexpected error.'));
-        }
-        process.exit(1);
+    const result = await safeParseJson(response);
+    if (!response.ok) {
+        const errorMessage = result && isSaveErrorResponse(result) ? result.error : `HTTP ${response.status}`;
+        throw new SaveError(errorMessage, 'If the problem persists, run "embeddables login" or try again later.');
+    }
+    if (!result || !isSaveResponse(result)) {
+        throw new SaveError(`Invalid response from server (HTTP ${response.status}).`, 'The server returned an unexpected format. Try again or contact support if it persists.');
     }
+    const { newVersionNumber } = result.data;
+    console.log(pc.green(`✓ Saved as version ${newVersionNumber}`));
+    // Update _version in config.json so future saves know the base version
+    setVersionInConfig(embeddableId, newVersionNumber);
+    // Also save the versioned file to .generated/ as a snapshot
+    const versionedPath = path.join(generatedDir, `embeddable-v${newVersionNumber}.json`);
+    fs.mkdirSync(generatedDir, { recursive: true });
+    fs.writeFileSync(versionedPath, jsonContent, 'utf8');
+    console.log(pc.cyan(`✓ Saved version file to ${versionedPath}`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embeddables/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "bin": {
     "embeddables": "./bin/embeddables.mjs"