@convosite/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,119 @@
-# 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_...
+```
+
+## 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.
+
+## Pull
+
+```bash
+npx convosite pull
+```
+
+Pull downloads the latest block definitions from Convosite. New block definitions are created locally and unchanged definitions are left alone. If a local `block.json` differs from Convosite, the file is reported as a conflict and is not overwritten.
+
+To make Convosite authoritative for the local block definitions:
+
+```bash
+npx convosite pull --force
+```
+
+`--force` overwrites conflicting `block.json` files and removes local `block.json` definitions that no longer exist in Convosite. It does **not** delete component/source files alongside a block; a block directory is only removed when it becomes empty.
+
+## 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 pull [--force]
+convosite push
+```

package/dist/api.d.ts

@@ -0,0 +1,28 @@
+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 interface PullResponse {
+    blocks: Array<{
+        key: string;
+        name: string;
+        description?: string | null;
+        props?: unknown[];
+    }>;
+}
+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>;
+export declare function pullBlocks(token: string): Promise<PullResponse>;

package/dist/api.js

@@ -0,0 +1,63 @@
+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 });
+}
+export async function pullBlocks(token) {
+    return request("/api/cli/pull", token, undefined, "GET");
+}
+async function request(endpoint, token, body, method = "POST") {
+    const apiUrl = getApiUrl();
+    let response;
+    try {
+        response = await fetch(`${apiUrl}${endpoint}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            ...(body === undefined
+                ? {}
+                : { 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/pull.d.ts

@@ -0,0 +1,5 @@
+interface PullOptions {
+    force?: boolean;
+}
+export declare function pull(options?: PullOptions): Promise<void>;
+export {};

package/dist/commands/pull.js

@@ -0,0 +1,151 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ApiError, pullBlocks } from "../api.js";
+import { loadConfig } from "../config.js";
+import { printApiError } from "../errors.js";
+export async function pull(options = {}) {
+    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();
+    const blocksRoot = path.resolve(process.cwd(), config.blocks);
+    console.log("Pulling from Convosite...");
+    try {
+        const result = await pullBlocks(token);
+        const remoteBlocks = result.blocks;
+        await fs.mkdir(blocksRoot, { recursive: true });
+        let created = 0;
+        let updated = 0;
+        let unchanged = 0;
+        let deleted = 0;
+        const conflicts = [];
+        const remoteKeys = new Set();
+        for (const block of remoteBlocks) {
+            remoteKeys.add(block.key);
+            const blockDirectory = path.join(blocksRoot, block.key);
+            const blockPath = path.join(blockDirectory, "block.json");
+            const remoteData = serialisableBlock(block);
+            const existing = await readJson(blockPath);
+            if (existing === null) {
+                await fs.mkdir(blockDirectory, { recursive: true });
+                await writeJson(blockPath, remoteData);
+                created++;
+                continue;
+            }
+            if (jsonEquals(existing, remoteData)) {
+                unchanged++;
+                continue;
+            }
+            if (!options.force) {
+                conflicts.push(relativePath(blockPath));
+                continue;
+            }
+            await writeJson(blockPath, remoteData);
+            updated++;
+        }
+        if (options.force) {
+            deleted = await removeMissingBlockDefinitions(blocksRoot, remoteKeys);
+        }
+        console.log("");
+        console.log("✓ Pull complete");
+        console.log("");
+        console.log(`  Created: ${created}`);
+        console.log(`  Updated: ${updated}`);
+        console.log(`  Unchanged: ${unchanged}`);
+        if (options.force) {
+            console.log(`  Deleted: ${deleted}`);
+        }
+        if (conflicts.length > 0) {
+            console.log("");
+            console.error(`${conflicts.length} local file${conflicts.length === 1 ? " has" : "s have"} changes and ${conflicts.length === 1 ? "was" : "were"} not overwritten:`);
+            console.error("");
+            for (const conflict of conflicts) {
+                console.error(`  ${conflict}`);
+            }
+            console.error("");
+            console.error("Run convosite pull --force to overwrite local block definitions.");
+            console.error("");
+            process.exitCode = 1;
+            return;
+        }
+        console.log("");
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            printApiError(error, []);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}
+function serialisableBlock(block) {
+    return {
+        key: block.key,
+        name: block.name,
+        description: block.description ?? "",
+        props: block.props ?? [],
+    };
+}
+async function readJson(filePath) {
+    try {
+        const contents = await fs.readFile(filePath, "utf8");
+        return JSON.parse(contents);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        if (error instanceof SyntaxError) {
+            return Symbol("invalid-json");
+        }
+        throw error;
+    }
+}
+async function writeJson(filePath, data) {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+function jsonEquals(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+async function removeMissingBlockDefinitions(blocksRoot, remoteKeys) {
+    const entries = await fs.readdir(blocksRoot, {
+        withFileTypes: true,
+    });
+    let deleted = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || remoteKeys.has(entry.name)) {
+            continue;
+        }
+        const blockPath = path.join(blocksRoot, entry.name, "block.json");
+        try {
+            await fs.unlink(blockPath);
+            deleted++;
+            await removeDirectoryIfEmpty(path.dirname(blockPath));
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return deleted;
+}
+async function removeDirectoryIfEmpty(directory) {
+    const entries = await fs.readdir(directory);
+    if (entries.length === 0) {
+        await fs.rmdir(directory);
+    }
+}
+function relativePath(filePath) {
+    return path
+        .relative(process.cwd(), filePath)
+        .replaceAll("\\", "/");
+}

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,38 @@
+#!/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 { pull } from "./commands/pull.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("pull")
+    .description("Pull block definitions from Convosite")
+    .option("--force", "Overwrite local block definitions and remove missing definitions")
+    .action((options) => runCommand(() => pull(options)));
+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.2.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"
+  }
+}