@convosite/cli 0.1.0 → 0.2.0

package/README.md

@@ -36,12 +36,6 @@ Add your access token to the project's `.env` file:
 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
@@ -90,6 +84,22 @@ 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
@@ -104,5 +114,6 @@ A push synchronizes the local block definitions with Convosite. Local block defi
 convosite init
 convosite make:block <name>
 convosite validate
+convosite pull [--force]
 convosite push
 ```

package/dist/api.d.ts

@@ -10,6 +10,14 @@ 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[]>;
@@ -17,3 +25,4 @@ export declare class ApiError extends Error {
 }
 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

@@ -15,18 +15,23 @@ export async function pushBlocks(token, blocks) {
 export async function validateBlocks(token, blocks) {
     return request("/api/cli/validate", token, { blocks });
 }
-async function request(endpoint, token, body) {
+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: "POST",
+            method,
             headers: {
                 Authorization: `Bearer ${token}`,
                 Accept: "application/json",
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify(body),
+            ...(body === undefined
+                ? {}
+                : { body: JSON.stringify(body) }),
         });
     }
     catch {

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/index.js

@@ -3,6 +3,7 @@ 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";
@@ -25,6 +26,11 @@ 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")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convosite/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Command-line tools for Convosite projects",
   "type": "module",
   "bin": {