@convosite/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @convosite/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line tools for building and syncing Convosite projects.
+
+## Requirements
+
+- Node.js 20 or newer
+- A Convosite site and access token
+
+## Install
+
+```bash
+npm install --save-dev @convosite/cli
+```
+
+You can then run commands with `npx convosite`, or install the package globally if you prefer a global `convosite` command.
+
+## Configure
+
+Initialize Convosite in the root of your frontend project:
+
+```bash
+npx convosite init
+```
+
+This creates:
+
+```text
+convosite.config.json
+blocks/
+```
+
+Add your access token to the project's `.env` file:
+
+```env
+CONVOSITE_ACCESS_TOKEN=cvt_...
+```
+
+The production API defaults to `https://app.convosite.io`. For local development you can override it:
+
+```env
+CONVOSITE_API_URL=http://convosite-v5.local
+```
+
+## Create a block
+
+```bash
+npx convosite make:block hero
+```
+
+This creates `blocks/hero/block.json`:
+
+```json
+{
+  "key": "hero",
+  "name": "Hero",
+  "description": "",
+  "props": []
+}
+```
+
+`key` is the block's stable machine identifier. Keep it unchanged when renaming a block. `name` is the human-readable display name.
+
+A block with fields can look like:
+
+```json
+{
+  "key": "hero",
+  "name": "Hero",
+  "description": "Primary page hero.",
+  "props": [
+    {
+      "key": "heading",
+      "type": "text",
+      "label": "Heading",
+      "required": true,
+      "rules": {
+        "max_chars": 120
+      }
+    }
+  ]
+}
+```
+
+## Validate
+
+```bash
+npx convosite validate
+```
+
+Validation is performed by Convosite, using the same server-side validation used by `push`. Validation does not modify the site's blocks.
+
+## Push
+
+```bash
+npx convosite push
+```
+
+A push synchronizes the local block definitions with Convosite. Local block definitions are authoritative: blocks missing from the push may be removed from the site.
+
+## Commands
+
+```text
+convosite init
+convosite make:block <name>
+convosite validate
+convosite push
+```

package/dist/api.d.ts

@@ -0,0 +1,19 @@
+import type { BlockFile } from "./block.js";
+export interface PushResponse {
+    site: string;
+    received: number;
+    created: number;
+    updated: number;
+    deleted: number;
+}
+export interface ValidateResponse {
+    valid: boolean;
+    received: number;
+}
+export declare class ApiError extends Error {
+    status: number;
+    errors: Record<string, string[]>;
+    constructor(status: number, message: string, errors?: Record<string, string[]>);
+}
+export declare function pushBlocks(token: string, blocks: BlockFile[]): Promise<PushResponse>;
+export declare function validateBlocks(token: string, blocks: BlockFile[]): Promise<ValidateResponse>;

package/dist/api.js

@@ -0,0 +1,58 @@
+const DEFAULT_API_URL = "https://app.convosite.io";
+export class ApiError extends Error {
+    status;
+    errors;
+    constructor(status, message, errors = {}) {
+        super(message);
+        this.status = status;
+        this.errors = errors;
+        this.name = "ApiError";
+    }
+}
+export async function pushBlocks(token, blocks) {
+    return request("/api/cli/push", token, { blocks });
+}
+export async function validateBlocks(token, blocks) {
+    return request("/api/cli/validate", token, { blocks });
+}
+async function request(endpoint, token, body) {
+    const apiUrl = getApiUrl();
+    let response;
+    try {
+        response = await fetch(`${apiUrl}${endpoint}`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        throw new Error(`Could not connect to Convosite at ${apiUrl}`);
+    }
+    if (!response.ok) {
+        let error = {};
+        try {
+            error =
+                (await response.json());
+        }
+        catch {
+            // Response wasn't JSON.
+        }
+        throw new ApiError(response.status, error.message ??
+            `Convosite returned ${response.status}`, error.errors ?? {});
+    }
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new Error("Convosite returned an invalid response.");
+    }
+}
+function getApiUrl() {
+    const value = process.env.CONVOSITE_API_URL?.trim() ||
+        DEFAULT_API_URL;
+    return value.replace(/\/+$/, "");
+}

package/dist/block.d.ts

@@ -0,0 +1,5 @@
+export interface BlockFile {
+    path: string;
+    data: unknown;
+}
+export declare function findBlocks(blocksDirectory: string): Promise<BlockFile[]>;

package/dist/block.js

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function findBlocks(blocksDirectory) {
+    const root = path.resolve(process.cwd(), blocksDirectory);
+    const blocks = [];
+    async function walk(directory) {
+        const entries = await fs.readdir(directory, {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            if (entry.name !== "block.json") {
+                continue;
+            }
+            const contents = await fs.readFile(fullPath, "utf8");
+            let data;
+            try {
+                data = JSON.parse(contents);
+            }
+            catch {
+                throw new Error(`Invalid JSON in ${path.relative(process.cwd(), fullPath)}`);
+            }
+            blocks.push({
+                path: path.relative(root, fullPath),
+                data,
+            });
+        }
+    }
+    try {
+        await walk(root);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new Error(`Blocks directory not found: ${blocksDirectory}`);
+        }
+        throw error;
+    }
+    return blocks;
+}

package/dist/command.d.ts

@@ -0,0 +1 @@
+export declare function runCommand(command: () => Promise<void>): Promise<void>;

package/dist/command.js

@@ -0,0 +1,12 @@
+export async function runCommand(command) {
+    try {
+        await command();
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.message
+            : "Unknown error";
+        console.error(`\nError: ${message}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const CONFIG_FILE = "convosite.config.json";
+const BLOCKS_DIRECTORY = "blocks";
+export async function init() {
+    console.log("Convosite\n");
+    const cwd = process.cwd();
+    const configPath = path.join(cwd, CONFIG_FILE);
+    const blocksPath = path.join(cwd, BLOCKS_DIRECTORY);
+    if (await exists(configPath)) {
+        throw new Error(`${CONFIG_FILE} already exists`);
+    }
+    const config = {
+        blocks: `./${BLOCKS_DIRECTORY}`,
+    };
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+    await fs.mkdir(blocksPath, {
+        recursive: true,
+    });
+    console.log(`✓ Created ${CONFIG_FILE}`);
+    console.log(`✓ Created ${BLOCKS_DIRECTORY}/`);
+    console.log("");
+    console.log("Next:");
+    console.log("");
+    console.log("  Add your access token to .env:");
+    console.log("");
+    console.log("  CONVOSITE_ACCESS_TOKEN=cvt_...");
+    console.log("");
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/make-block.d.ts

@@ -0,0 +1 @@
+export declare function makeBlock(name: string): Promise<void>;

package/dist/commands/make-block.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "../config.js";
+export async function makeBlock(name) {
+    console.log("Convosite\n");
+    const config = await loadConfig();
+    const key = toKey(name);
+    if (!key) {
+        throw new Error("Block name must contain letters or numbers");
+    }
+    const displayName = toDisplayName(name);
+    const blockDirectory = path.resolve(process.cwd(), config.blocks, key);
+    const blockPath = path.join(blockDirectory, "block.json");
+    if (await exists(blockPath)) {
+        throw new Error(`Block "${key}" already exists`);
+    }
+    await fs.mkdir(blockDirectory, {
+        recursive: true,
+    });
+    const block = {
+        key,
+        name: displayName,
+        description: "",
+        props: [],
+    };
+    await fs.writeFile(blockPath, JSON.stringify(block, null, 2) + "\n", "utf8");
+    console.log(`✓ Created ${relativePath(blockPath)}`);
+    console.log("");
+}
+function toKey(value) {
+    return value
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[^a-zA-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .toLowerCase();
+}
+function toDisplayName(value) {
+    return value
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function relativePath(filePath) {
+    return path
+        .relative(process.cwd(), filePath)
+        .replaceAll("\\", "/");
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/push.d.ts

@@ -0,0 +1 @@
+export declare function push(): Promise<void>;

package/dist/commands/push.js

@@ -0,0 +1,37 @@
+import { loadConfig } from "../config.js";
+import { printApiError } from "../errors.js";
+import { findBlocks } from "../block.js";
+import { ApiError, pushBlocks, } from "../api.js";
+export async function push() {
+    console.log("Convosite\n");
+    const token = process.env.CONVOSITE_ACCESS_TOKEN;
+    if (!token) {
+        throw new Error("CONVOSITE_ACCESS_TOKEN is not set");
+    }
+    const config = await loadConfig();
+    console.log("Scanning blocks...");
+    const blocks = await findBlocks(config.blocks);
+    if (blocks.length === 0) {
+        throw new Error("No block.json files found");
+    }
+    console.log(`Found ${blocks.length} block${blocks.length === 1 ? "" : "s"}`);
+    console.log("Pushing to Convosite...");
+    try {
+        const result = await pushBlocks(token, blocks);
+        console.log("");
+        console.log("✓ Push complete");
+        console.log("");
+        console.log(`  Created: ${result.created}`);
+        console.log(`  Updated: ${result.updated}`);
+        console.log(`  Deleted: ${result.deleted}`);
+        console.log("");
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            printApiError(error, blocks);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1 @@
+export declare function validate(): Promise<void>;

package/dist/commands/validate.js

@@ -0,0 +1,33 @@
+import { loadConfig } from "../config.js";
+import { findBlocks } from "../block.js";
+import { ApiError, validateBlocks, } from "../api.js";
+import { printApiError } from "../errors.js";
+export async function validate() {
+    console.log("Convosite\n");
+    const token = process.env.CONVOSITE_ACCESS_TOKEN;
+    if (!token) {
+        throw new Error("CONVOSITE_ACCESS_TOKEN is not set");
+    }
+    const config = await loadConfig();
+    console.log("Scanning blocks...");
+    const blocks = await findBlocks(config.blocks);
+    if (blocks.length === 0) {
+        throw new Error("No block.json files found");
+    }
+    console.log(`Found ${blocks.length} block${blocks.length === 1 ? "" : "s"}`);
+    console.log("Validating...");
+    try {
+        const result = await validateBlocks(token, blocks);
+        console.log("");
+        console.log(`✓ ${result.received} block${result.received === 1 ? "" : "s"} valid`);
+        console.log("");
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            printApiError(error, blocks);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export interface ConvositeConfig {
+    blocks: string;
+}
+export declare function loadConfig(): Promise<ConvositeConfig>;

package/dist/config.js

@@ -0,0 +1,28 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function loadConfig() {
+    const configPath = path.resolve(process.cwd(), "convosite.config.json");
+    let contents;
+    try {
+        contents = await fs.readFile(configPath, "utf8");
+    }
+    catch {
+        throw new Error("Could not find convosite.config.json");
+    }
+    let config;
+    try {
+        config = JSON.parse(contents);
+    }
+    catch {
+        throw new Error("convosite.config.json contains invalid JSON");
+    }
+    if (typeof config !== "object" ||
+        config === null ||
+        !("blocks" in config) ||
+        typeof config.blocks !== "string") {
+        throw new Error('convosite.config.json must contain a "blocks" property');
+    }
+    return {
+        blocks: config.blocks,
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1 @@
+export declare function loadEnv(): void;

package/dist/env.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+import dotenv from "dotenv";
+export function loadEnv() {
+    dotenv.config({
+        path: path.resolve(process.cwd(), ".env"),
+        quiet: true,
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+import type { BlockFile } from "./block.js";
+import { ApiError } from "./api.js";
+export declare function printApiError(error: ApiError, blocks: BlockFile[]): void;

package/dist/errors.js

@@ -0,0 +1,53 @@
+export function printApiError(error, blocks) {
+    console.error("");
+    if (error.status === 401) {
+        console.error("Authentication failed.");
+        console.error("");
+        console.error(`  ${error.message}`);
+        console.error("");
+        return;
+    }
+    if (error.status === 403) {
+        console.error("Access denied.");
+        console.error("");
+        console.error(`  ${error.message}`);
+        console.error("");
+        return;
+    }
+    if (error.status === 422) {
+        console.error("Validation failed");
+        console.error("");
+        for (const [field, messages] of Object.entries(error.errors)) {
+            printValidationError(field, messages, blocks);
+        }
+        return;
+    }
+    console.error(`Convosite returned an error (${error.status}).`);
+    console.error("");
+    console.error(`  ${error.message}`);
+    console.error("");
+}
+function printValidationError(field, messages, blocks) {
+    const match = field.match(/^blocks\.(\d+)\.data(?:\.(.+))?$/);
+    if (!match) {
+        console.error(`  ${field}`);
+        for (const message of messages) {
+            console.error(`    ${message}`);
+        }
+        console.error("");
+        return;
+    }
+    const index = Number(match[1]);
+    const property = match[2];
+    const block = blocks[index];
+    if (block) {
+        console.error(block.path);
+    }
+    if (property) {
+        console.error(`  ${property}`);
+    }
+    for (const message of messages) {
+        console.error(`  ${message}`);
+    }
+    console.error("");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runCommand } from "./command.js";
+import { init } from "./commands/init.js";
+import { makeBlock } from "./commands/make-block.js";
+import { push } from "./commands/push.js";
+import { validate } from "./commands/validate.js";
+import { loadEnv } from "./env.js";
+loadEnv();
+const program = new Command();
+program
+    .name("convosite")
+    .description("CLI for Convosite")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize Convosite in your project")
+    .action(() => runCommand(init));
+program
+    .command("make:block")
+    .description("Create a new Convosite block")
+    .argument("<name>", "Block name")
+    .action((name) => runCommand(() => makeBlock(name)));
+program
+    .command("validate")
+    .description("Validate your Convosite project")
+    .action(() => runCommand(validate));
+program
+    .command("push")
+    .description("Push your project structure to Convosite")
+    .action(() => runCommand(push));
+program.parse();

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@convosite/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Command-line tools for Convosite projects",
+  "type": "module",
+  "bin": {
+    "convosite": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "dotenv": "^18.0.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "typescript": "^5.9.0"
+  }
+}