@superblocksteam/cli 0.0.20 → 0.0.21

package/README.md

@@ -12,7 +12,7 @@ $ npm install -g @superblocksteam/cli
 $ superblocks COMMAND
 running command...
 $ superblocks (--version)
-@superblocksteam/cli/0.0.20 linux-x64 node-v18.17.0
+@superblocksteam/cli/0.0.21 linux-x64 node-v18.17.0
 $ superblocks --help [COMMAND]
 USAGE
   $ superblocks COMMAND
@@ -29,6 +29,7 @@ USAGE
 * [`superblocks help [COMMANDS]`](#superblocks-help-commands)
 * [`superblocks init [RESOURCEURL]`](#superblocks-init-resourceurl)
 * [`superblocks login`](#superblocks-login)
+* [`superblocks migrate`](#superblocks-migrate)
 * [`superblocks pull [ONLY]`](#superblocks-pull-only)
 
 ## `superblocks components create`
@@ -154,7 +155,7 @@ EXAMPLES
 
 ## `superblocks login`
 
-Authenticates with Superblocks cloud
+Authenticate with Superblocks cloud
 
 ```
 USAGE
@@ -164,7 +165,22 @@ FLAGS
   -t, --token=<value>  Superblocks user API key
 
 DESCRIPTION
-  Authenticates with Superblocks cloud
+  Authenticate with Superblocks cloud
+```
+
+## `superblocks migrate`
+
+Migrate files to use the current CLI version
+
+```
+USAGE
+  $ superblocks migrate
+
+DESCRIPTION
+  Migrate files to use the current CLI version
+
+EXAMPLES
+  $ superblocks migrate
 ```
 
 ## `superblocks pull [ONLY]`

package/assets/custom-components/example/component.tsx

@@ -1,20 +1,23 @@
 import React, { useCallback, useState } from "react";
+import { useSuperblocksContext } from "@superblocksteam/custom-components";
+import { type Props, type EventTriggers } from "./types";
 import { Task, ErrorComponent, validateTasks } from "./validation";
-import { Props } from "./types";
 import "./main.scss";
 
-export default function Component({
-  updateStatefulProperties,
-  tasks,
-  onTaskAdded,
-  onTaskStatusChanged,
-}: Props) {
-  const { validatedTasks, hasError } = validateTasks(tasks);
+export default function Component({ tasks }: Props) {
+  const {
+    updateProperties,
+    events : {
+      onTaskAdded,
+      onTaskStatusChanged,
+    },
+  } = useSuperblocksContext<Props, EventTriggers>();
+  const { validatedTasks, hasError } = validateTasks(tasks ?? {});
   const [value, setValue] = useState("");
 
   const onTodoAdded = useCallback(() => {
     const id = Math.random().toString(36).substring(2, 8);
-    updateStatefulProperties({
+    updateProperties({
       tasks: {
         ...validatedTasks,
         [id]: {
@@ -24,11 +27,11 @@ export default function Component({
       },
     });
     onTaskAdded();
-  }, [updateStatefulProperties, validatedTasks, value, onTaskAdded]);
+  }, [updateProperties, validatedTasks, value, onTaskAdded]);
 
   const onTaskStatusChange = useCallback(
     (id: string, status: boolean) => {
-      updateStatefulProperties({
+      updateProperties({
         tasks: {
           ...validatedTasks,
           [id]: {
@@ -39,7 +42,7 @@ export default function Component({
       });
       onTaskStatusChanged();
     },
-    [updateStatefulProperties, validatedTasks, tasks, onTaskStatusChanged]
+    [updateProperties, validatedTasks, tasks, onTaskStatusChanged]
   );
 
   return hasError ? (

package/assets/custom-components/setup/package.json

@@ -7,7 +7,7 @@
     "lint:fix": "npx eslint . --fix"
   },
   "dependencies": {
-    "@superblocksteam/custom-components": "0.0.20",
+    "@superblocksteam/custom-components": "0.0.21",
     "react": "^18",
     "react-dom": "^18"
   },

package/dist/commands/components/create.d.ts

@@ -1,6 +1,7 @@
 import { AuthenticatedApplicationCommand } from "../../common/authenticated-command";
 export default class CreateComponent extends AuthenticatedApplicationCommand {
     static description: string;
+    private dataTypeToDefaultControlType;
     private initializeComponentByWizard;
     private initializeComponentByExample;
     run(): Promise<void>;

package/dist/commands/components/create.js

@@ -27,11 +27,26 @@ const tsStringify = (obj) => {
     return `{\n${stringifiedEntries.join(",\n")}\n},\n`;
 };
 class CreateComponent extends authenticated_command_1.AuthenticatedApplicationCommand {
+    constructor() {
+        super(...arguments);
+        this.dataTypeToDefaultControlType = (propertyType) => {
+            switch (propertyType) {
+                case "any":
+                    return "js-expr";
+                case "boolean":
+                    return "switch";
+                default:
+                    return "text";
+            }
+        };
+    }
     async initializeComponentByWizard(isFirstTimeCreate) {
+        this.log(`${(0, colorette_1.cyanBright)("ℹ")}  Follow this wizard to configure your Custom Component. You can always edit the generated config.ts file directly to modify your properties or events.`);
+        this.log();
         const displayName = (await (0, enquirer_1.prompt)({
             type: "input",
             name: "displayName",
-            message: "What is the display name of the component you want to create? (e.g. Date Picker)",
+            message: "What is the display name of the component you want to create? (e.g. To-Do List)",
             validate: (response) => !(0, lodash_1.isEmpty)(response.trim()),
         })).displayName;
         const name = (await (0, enquirer_1.prompt)({
@@ -39,112 +54,121 @@ class CreateComponent extends authenticated_command_1.AuthenticatedApplicationCo
             name: "name",
             message: "What is the machine readable name of the component you want to create?",
             validate: (response) => (0, identifiers_1.isValidIdentifier)(response) || "Invalid identifier",
-            initial: (0, identifiers_1.suggestIdentifier)(displayName, true) || "DatePicker",
+            initial: (0, identifiers_1.suggestIdentifier)(displayName, true) || "ToDoList",
         })).name;
         this.log();
-        this.log(`${(0, colorette_1.cyanBright)("ℹ")}  A ${(0, colorette_1.bold)("stateful property")} determines what shows up in the properties panel of a custom component`);
+        this.log(`${(0, colorette_1.cyanBright)("ℹ")}  Properties represent the state of the component. You will define how each property is made available to the rest of your App and whether each property is displayed in the Properties Panel. Read more about properties here: ${(0, colorette_1.magenta)("https://docs.superblocks.com/applications/custom-components/#properties--events")}`);
         this.log();
-        const hasStatefulProps = (await (0, enquirer_1.prompt)({
+        const hasProperties = (await (0, enquirer_1.prompt)({
             type: "confirm",
-            name: "hasStatefulProps",
-            message: `Does this component have ${(0, colorette_1.bold)("stateful properties")}?`,
+            name: "hasProperties",
+            message: `Does this component have ${(0, colorette_1.bold)("properties")}?`,
             initial: false,
-        })).hasStatefulProps;
-        const statefulProps = [];
-        if (hasStatefulProps) {
+        })).hasProperties;
+        const properties = [];
+        if (hasProperties) {
             for (;;) {
-                const statefulPropName = (await (0, enquirer_1.prompt)({
-                    type: "input",
-                    name: "statefulPropName",
-                    message: "What is the label of the stateful prop? (e.g. Selected Date)",
-                    validate: (response) => !(0, lodash_1.isEmpty)(response.trim()),
-                })).statefulPropName.trim();
-                const statefulPropPath = (await (0, enquirer_1.prompt)({
+                const propertyPath = (await (0, enquirer_1.prompt)({
                     type: "input",
                     name: "path",
-                    initial: (0, identifiers_1.suggestIdentifier)(statefulPropName) || "selectedDate",
-                    message: "What is the machine readable name of the stateful prop?",
+                    message: "What is the path of the property? This will be used to access the property in your code (e.g. currentTasks)",
                     validate: (response) => {
                         if (!(0, identifiers_1.isValidIdentifier)(response))
                             return "Invalid identifier";
-                        if (statefulProps.some((v) => v.path === response))
+                        if (properties.some((v) => v.path === response))
                             return "Duplicate property name";
                         return true;
                     },
                 })).path;
-                const statefulPropType = (await (0, enquirer_1.prompt)({
+                const propertyType = (await (0, enquirer_1.prompt)({
                     type: "select",
                     name: "type",
-                    message: `What input type should ${statefulPropName} be?`,
-                    choices: Object.entries(util_1.inputTypeDefinions).map(([k, v]) => ({
+                    message: `What is the type of ${propertyPath}?`,
+                    choices: Object.entries(util_1.dataTypeDefinions).map(([k, v]) => ({
                         name: k,
                         message: v.prompt,
                         value: k,
                     })),
                     initial: 0,
                 })).type;
-                const placeholderText = (await (0, enquirer_1.prompt)({
-                    type: "input",
+                const showInPropsPanel = (await (0, enquirer_1.prompt)({
                     name: "value",
-                    message: `What placeholder text should ${statefulPropName} have, if any?`,
-                    required: false,
+                    type: "confirm",
+                    message: "Should this property be shown in the properties panel?",
+                    initial: true,
                 })).value;
-                statefulProps.push({
-                    label: statefulPropName,
-                    path: statefulPropPath,
-                    inputType: statefulPropType,
-                    placeholder: placeholderText || undefined,
+                let propertiesPanelDisplay = undefined;
+                if (showInPropsPanel) {
+                    this.log();
+                    this.log((0, colorette_1.bold)("Properties Panel Display Configuration"));
+                    const propertyLabel = (await (0, enquirer_1.prompt)({
+                        type: "input",
+                        name: "label",
+                        message: "What is the label of the property? (e.g. Tasks)",
+                        validate: (response) => !(0, lodash_1.isEmpty)(response.trim()),
+                    })).label.trim();
+                    propertiesPanelDisplay = {
+                        label: propertyLabel,
+                        controlType: this.dataTypeToDefaultControlType(propertyType),
+                    };
+                }
+                properties.push({
+                    path: propertyPath,
+                    dataType: propertyType,
+                    propertiesPanelDisplay,
                 });
-                const addAnotherStatefulProp = (await (0, enquirer_1.prompt)({
+                this.log(`You can configure the remaining display attributes (tooltip, placeholder, etc) in the config.ts file directly.`);
+                this.log();
+                const addAnotherProperty = (await (0, enquirer_1.prompt)({
                     type: "confirm",
                     name: "value",
-                    message: "Do you want to add another stateful prop?",
+                    message: "Do you want to add another property?",
                     initial: false,
                 })).value;
-                if (!addAnotherStatefulProp) {
+                if (!addAnotherProperty) {
                     break;
                 }
             }
         }
         this.log();
-        this.log(`${(0, colorette_1.cyanBright)("ℹ")} ${(0, colorette_1.bold)("Event handlers")} represent the events your custom component can fire`);
+        this.log(`${(0, colorette_1.cyanBright)("ℹ")} ${(0, colorette_1.bold)("Events")} represent the types of events that the component can trigger in Superblocks. Learn more about events: ${(0, colorette_1.magenta)("https://docs.superblocks.com/applications/custom-components/#properties--events")}`);
         this.log();
         const hasEventHandlers = (await (0, enquirer_1.prompt)({
             type: "confirm",
             name: "value",
-            message: `Does this component have ${(0, colorette_1.bold)("event handlers")}? (e.g. a date picker component that has a On Change event handler)`,
+            message: `Does this component have ${(0, colorette_1.bold)("events")}? (e.g. a date picker component that triggers an On Change event)`,
             initial: false,
         })).value;
-        const eventHandlers = [];
+        const events = [];
         if (hasEventHandlers) {
             for (;;) {
                 const eventHandlerName = (await (0, enquirer_1.prompt)({
                     name: "value",
                     type: "input",
-                    message: "What is the label of the event handler? (e.g. On Change)",
+                    message: "What is the label of the event? (e.g. On Change)",
                     validate: (response) => !(0, lodash_1.isEmpty)(response.trim()),
                 })).value.trim();
                 const eventHandlerPath = (await (0, enquirer_1.prompt)({
                     name: "value",
-                    message: "What is the machine readable name of the event handler?",
+                    message: "What is the path of the event? This will be used to trigger the event in your code (e.g. onChange)",
                     type: "input",
                     initial: (0, identifiers_1.suggestIdentifier)(eventHandlerName) || "onChange",
                     validate: (response) => {
                         if (!(0, identifiers_1.isValidIdentifier)(response))
                             return "Invalid identifier";
-                        if (eventHandlers.some((v) => v.path === response))
+                        if (events.some((v) => v.path === response))
                             return "Duplicate property name";
                         return true;
                     },
                 })).value;
-                eventHandlers.push({
+                events.push({
                     label: eventHandlerName,
                     path: eventHandlerPath,
                 });
                 const addAnotherEventHandler = (await (0, enquirer_1.prompt)({
                     name: "value",
                     type: "confirm",
-                    message: "Do you want to add another event handler?",
+                    message: "Do you want to add another event?",
                     initial: false,
                 })).value;
                 if (!addAnotherEventHandler) {
@@ -156,14 +180,14 @@ class CreateComponent extends authenticated_command_1.AuthenticatedApplicationCo
             id: (0, node_crypto_1.randomUUID)(),
             name,
             displayName,
-            statefulPropsRendered: statefulProps
-                .map((statefulProp) => tsStringify(statefulProp))
+            propertiesRendered: properties
+                .map((property) => tsStringify(property))
                 .join(""),
-            eventHandlersRendered: eventHandlers
+            eventHandlersRendered: events
                 .map((eventHandler) => tsStringify(eventHandler))
                 .join(""),
         });
-        const componentTsx = (0, create_component_defaults_1.getDefaultComponentTsx)(statefulProps, eventHandlers.map((prop) => prop.path));
+        const componentTsx = (0, create_component_defaults_1.getDefaultComponentTsx)(properties, events.map((prop) => prop.path));
         if (isFirstTimeCreate) {
             await fs.copy(DEFAULT_PACKAGE_JSON_TEMPLATE_PATH, ".");
         }
@@ -173,23 +197,26 @@ class CreateComponent extends authenticated_command_1.AuthenticatedApplicationCo
         return {
             name,
             displayName,
-            statefulProps,
-            eventHandlers,
+            properties,
+            events,
         };
     }
     async initializeComponentByExample() {
         const response = {
-            displayName: "Example Component",
-            name: "ExampleComponent",
-            statefulProps: [
+            displayName: "To-Do List (Example)",
+            name: "ToDoList",
+            properties: [
                 {
-                    label: "Default Tasks",
                     path: "tasks",
-                    inputType: "js",
-                    placeholder: "{ taskId: { taskName: 'Task Name', taskStatus: 'complete' | 'todo' } }",
+                    dataType: "any",
+                    propertiesPanelDisplay: {
+                        label: "Default Tasks",
+                        placeholder: "{ taskId: { taskName: 'Task Name', taskStatus: 'complete' | 'todo' } }",
+                        controlType: "js-expr",
+                    },
                 },
             ],
-            eventHandlers: [
+            events: [
                 {
                     label: "On Task Added",
                     path: "onTaskAdded",
@@ -204,10 +231,10 @@ class CreateComponent extends authenticated_command_1.AuthenticatedApplicationCo
             id: (0, node_crypto_1.randomUUID)(),
             name: response.name,
             displayName: response.displayName,
-            statefulPropsRendered: response.statefulProps
-                .map((statefulProp) => tsStringify(statefulProp))
+            propertiesRendered: response.properties
+                .map((property) => tsStringify(property))
                 .join(""),
-            eventHandlersRendered: response.eventHandlers
+            eventHandlersRendered: response.events
                 .map((eventHandler) => tsStringify(eventHandler))
                 .join(""),
         });
@@ -218,31 +245,38 @@ class CreateComponent extends authenticated_command_1.AuthenticatedApplicationCo
         return response;
     }
     async run() {
+        this.log();
         const isFirstTimeCreate = !(await fs.exists("package.json"));
-        const initExampleComponent = isFirstTimeCreate &&
-            (await (0, enquirer_1.prompt)({
+        let response;
+        if (isFirstTimeCreate) {
+            this.log(`${(0, colorette_1.cyanBright)("ℹ")} Welcome to Custom Components! In order to help you get started, we’ve built an example To-Do List Component. You can use this component as a template as you build your own Custom Component. To work with this component, we recommend following along with our quickstart guide: ${(0, colorette_1.magenta)("https://docs.superblocks.com/applications/custom-components/quickstart")}`);
+            this.log();
+            this.log(`If you choose to generate the example component, you will not have to provide any additional inputs. You can re-run superblocks components create once you are ready to create your own component from scratch. `);
+            this.log();
+            const initExampleComponent = (await (0, enquirer_1.prompt)({
                 name: "value",
                 type: "confirm",
-                message: "Would you like to use a pre-generated example custom component?",
+                message: "Would you like to generate an example custom component?",
                 initial: false,
             })).value;
-        let response;
-        if (!initExampleComponent) {
-            response = await this.initializeComponentByWizard(isFirstTimeCreate);
+            response = initExampleComponent
+                ? await this.initializeComponentByExample()
+                : await this.initializeComponentByWizard(isFirstTimeCreate);
         }
         else {
-            response = await this.initializeComponentByExample();
+            response = await this.initializeComponentByWizard(isFirstTimeCreate);
         }
         this.log((0, colorette_1.green)("Successfully created component! Added the following files:"));
         this.log();
         const tree = core_1.ux.tree();
         tree.insert("components");
         tree.nodes.components.insert(response.name);
-        tree.nodes.components.nodes[response.name].insert("config.ts # update this file to configure your component's properties panel");
+        tree.nodes.components.nodes[response.name].insert("config.ts # update this file to manage your component's properties and events");
+        tree.nodes.components.nodes[response.name].insert("types.ts # this file contains your react component type definitions and is automatically updated while you run 'superblocks components watch'");
         tree.nodes.components.nodes[response.name].insert("component.tsx # your component's react code");
         tree.display();
         this.log();
-        this.log(`${(0, colorette_1.green)("Remember to run $ ")}${(0, colorette_1.cyan)("superblocks components watch")}${(0, colorette_1.green)(" to watch for changes to your component files")}`);
+        this.log(`${(0, colorette_1.green)("Remember to run $ ")}${(0, colorette_1.magenta)("superblocks components watch")}${(0, colorette_1.green)(" to watch for changes to your component files")}`);
         this.log();
         this.log(`Edit your component's react code here:
       ${(0, colorette_1.green)(`components/${response.name}/component.tsx`)}`);

package/dist/commands/components/watch.js

@@ -32,7 +32,6 @@ class Watch extends authenticated_command_1.AuthenticatedApplicationCommand {
         await this.registerComponents();
         this.log((0, colorette_1.yellow)("Remember to refresh your application to see any newly registered components."));
         this.log();
-        this.log((0, colorette_1.green)(`Visit ${await this.getBaseUrl()} and access your application in edit mode to see your components! 🐨`));
         const port = 3002;
         const editModeUrl = await this.getEditModeUrl();
         const viteLogger = (0, vite_1.createLogger)();
@@ -71,7 +70,7 @@ class Watch extends authenticated_command_1.AuthenticatedApplicationCommand {
             this.log();
             this.log((0, colorette_1.bold)((0, colorette_1.magenta)(`${editModeUrl}?devMode=true`)));
             this.log();
-            this.log((0, colorette_1.yellow)("Remember to refresh your already open Application page and turn on local development in Superblocks to connect to your local server!"));
+            this.log((0, colorette_1.yellow)(`Please ensure that Local Dev Mode is enabled in your Application so that the component is fetched from your local dev server. Learn more about Local Dev Mode here: ${(0, colorette_1.magenta)("https://docs.superblocks.com/applications/custom-components/development-lifecycle#local-development-mode")}`));
         })();
     }
 }

package/dist/commands/init.js

@@ -265,7 +265,7 @@ function getResourceIdFromUrl(resourceUrl) {
         return [url.pathname.split("/")[2], "APPLICATION"];
     }
     else if (url.pathname.startsWith("/workflows") ||
-        url.pathname.startsWith("/scheduled-jobs")) {
+        url.pathname.startsWith("/scheduled_jobs")) {
         return [url.pathname.split("/")[2], "BACKEND"];
     }
     throw new Error(`Failed to parse resource URL: ${resourceUrl}`);

package/dist/commands/login.js

@@ -49,7 +49,7 @@ class Login extends core_1.Command {
         }
     }
 }
-Login.description = "Authenticates with Superblocks cloud";
+Login.description = "Authenticate with Superblocks cloud";
 Login.flags = {
     // flag with a value (-t, --token=VALUE)
     token: core_1.Flags.string({

package/dist/commands/migrate.d.ts

@@ -0,0 +1,9 @@
+import { AuthenticatedCommand } from "../common/authenticated-command";
+export default class Migrate extends AuthenticatedCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+    private createTasks;
+    private getResourceIdsToMigrate;
+    private migrateApplication;
+}

package/dist/commands/migrate.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const node_util_1 = tslib_1.__importDefault(require("node:util"));
+const util_1 = require("@superblocksteam/util");
+const colorette_1 = require("colorette");
+const fs = tslib_1.__importStar(require("fs-extra"));
+const listr2_1 = require("listr2");
+const semver_1 = tslib_1.__importDefault(require("semver"));
+const authenticated_command_1 = require("../common/authenticated-command");
+const version_control_1 = require("../common/version-control");
+class Migrate extends authenticated_command_1.AuthenticatedCommand {
+    async run() {
+        const tasks = this.createTasks();
+        await tasks.run();
+    }
+    createTasks() {
+        const tasks = new listr2_1.Listr([
+            {
+                title: "Checking for existing Superblocks project...",
+                task: async (ctx) => {
+                    try {
+                        [
+                            ctx.existingSuperblocksRootConfig,
+                            ctx.superblocksRootConfigPath,
+                        ] = await (0, util_1.getSuperblocksMonorepoConfigJson)(true);
+                        ctx.existingSuperblocksResourceConfig =
+                            await (0, util_1.getSuperblocksResourceConfigIfExists)();
+                    }
+                    catch {
+                        // no existing superblocks config
+                        this.error(`No Superblocks project found in the current folder hierarchy. Run ${(0, colorette_1.cyan)("superblocks init")} to initialize a new project.`);
+                    }
+                },
+            },
+            {
+                title: "Migrating resources...",
+                task: async (ctx, task) => {
+                    var _a;
+                    const resourceIdsToMigrate = await this.getResourceIdsToMigrate(ctx, task);
+                    const subtasks = [];
+                    const superblocksRootPath = node_path_1.default.resolve(node_path_1.default.dirname(ctx.superblocksRootConfigPath), "..");
+                    for (const resourceId of resourceIdsToMigrate) {
+                        const resource = (_a = ctx.existingSuperblocksRootConfig) === null || _a === void 0 ? void 0 : _a.resources[resourceId];
+                        switch (resource === null || resource === void 0 ? void 0 : resource.resourceType) {
+                            case "APPLICATION": {
+                                subtasks.push({
+                                    title: `Migrating application ${resource.location}...`,
+                                    task: async (_ctx, task) => {
+                                        await this.migrateApplication(resource, superblocksRootPath);
+                                        task.title += `: done`;
+                                    },
+                                });
+                                break;
+                            }
+                            case "BACKEND": {
+                                subtasks.push({
+                                    title: `Migrating backend ${resource.location}...`,
+                                    task: async (_ctx, task) => {
+                                        task.title += `: done`;
+                                    },
+                                });
+                                break;
+                            }
+                            default: {
+                                this.error(`Unsupported resource type, resource: ${JSON.stringify(resource)}
+                    `);
+                            }
+                        }
+                    }
+                    return task.newListr(subtasks, {
+                        concurrent: true,
+                    });
+                },
+            },
+        ], {
+            concurrent: false,
+        });
+        return tasks;
+    }
+    async getResourceIdsToMigrate(ctx, task) {
+        var _a, _b, _c, _d, _e;
+        const choices = [];
+        const initialSelections = [];
+        choices.push({
+            name: "All Resources",
+            message: "",
+        });
+        let counter = 1;
+        for (const [resourceId, resource] of Object.entries((_b = (_a = ctx.existingSuperblocksRootConfig) === null || _a === void 0 ? void 0 : _a.resources) !== null && _b !== void 0 ? _b : {})) {
+            choices.push({
+                name: resourceId,
+                message: resource.location,
+            });
+            if (((_c = ctx.existingSuperblocksResourceConfig) === null || _c === void 0 ? void 0 : _c.id) === resourceId) {
+                initialSelections.push(counter);
+            }
+            counter++;
+        }
+        const resourceIdsToMigrate = choices.length === 1
+            ? [choices[0].name]
+            : await task.prompt([
+                {
+                    type: "MultiSelect",
+                    name: "resourceIdsToMigrate",
+                    message: `Select resources to migrate (${version_control_1.MULTI_SELECT_PROMPT_HELP})`,
+                    choices: choices,
+                    initial: initialSelections,
+                    validate: version_control_1.atLeastOneSelection,
+                    // @ts-expect-error listr2 types are wrong for prefix
+                    prefix: "▸",
+                    indicator: "◉",
+                },
+            ]);
+        if (resourceIdsToMigrate[0] === "All Resources") {
+            return Object.entries((_e = (_d = ctx.existingSuperblocksRootConfig) === null || _d === void 0 ? void 0 : _d.resources) !== null && _e !== void 0 ? _e : {}).map(([id]) => id);
+        }
+        return resourceIdsToMigrate;
+    }
+    async migrateApplication(applicationResource, superblocksRootPath) {
+        var _a;
+        this.log("Checking CLI version compatibility...");
+        try {
+            const packageJson = await fs.readJson(node_path_1.default.join(superblocksRootPath, applicationResource.location, "package.json"));
+            const versionStr = (_a = packageJson.dependencies) === null || _a === void 0 ? void 0 : _a["@superblocksteam/custom-components"];
+            if (!semver_1.default.satisfies(this.config.version, versionStr)) {
+                this.log("Migrating application dependencies...");
+                await node_util_1.default.promisify(node_child_process_1.exec)(`npm install @superblocksteam/custom-components@${this.config.version}`, {
+                    cwd: node_path_1.default.join(superblocksRootPath, applicationResource.location),
+                });
+            }
+            else {
+                this.log("CLI version matches package.json version");
+            }
+        }
+        catch (e) {
+            this.error(e.message, {
+                exit: 1,
+            });
+        }
+    }
+}
+Migrate.description = "Migrate files to use the current CLI version";
+Migrate.examples = ["<%= config.bin %> <%= command.id %>"];
+exports.default = Migrate;

package/dist/common/authenticated-command.d.ts

@@ -6,6 +6,7 @@ export declare abstract class AuthenticatedCommand extends Command {
     protected init(): Promise<void>;
     protected getBaseUrl(): Promise<string>;
     protected getSdk(): SuperblocksSdk;
+    protected runAutomatedDotfileUpdates(): Promise<void>;
 }
 export declare abstract class AuthenticatedApplicationCommand extends AuthenticatedCommand {
     applicationConfig: SuperblocksApplicationConfig;

package/dist/common/authenticated-command.js

@@ -2,10 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthenticatedApplicationCommand = exports.AuthenticatedCommand = void 0;
 const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
 const core_1 = require("@oclif/core");
 const sdk_1 = require("@superblocksteam/sdk");
 const util_1 = require("@superblocksteam/util");
+const colorette_1 = require("colorette");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const semver_1 = tslib_1.__importDefault(require("semver"));
+const yaml_1 = require("yaml");
+const migrationWarningsForApplications_1 = require("../util/migrationWarningsForApplications");
+const migrationsForDotfiles_1 = require("../util/migrationsForDotfiles");
+const version_control_1 = require("./version-control");
 class AuthenticatedCommand extends core_1.Command {
     async init() {
         await super.init();
@@ -16,7 +23,7 @@ class AuthenticatedCommand extends core_1.Command {
             }
             const { token, superblocksBaseUrl } = result;
             this.sdk = new sdk_1.SuperblocksSdk(token, superblocksBaseUrl);
-            await (0, util_1.updatedMonorepoConfig)(this.config.version);
+            await this.runAutomatedDotfileUpdates();
         }
         catch (e) {
             console.log(e.message);
@@ -34,6 +41,62 @@ class AuthenticatedCommand extends core_1.Command {
         }
         return this.sdk;
     }
+    async runAutomatedDotfileUpdates() {
+        let previousConfig;
+        let rootConfigPath;
+        try {
+            [previousConfig, rootConfigPath] = await (0, util_1.getSuperblocksMonorepoConfigJson)(true);
+        }
+        catch {
+            // This might fail for a brand-new project folder, which is deliberately ignored
+            return;
+        }
+        if (previousConfig &&
+            rootConfigPath &&
+            (0, migrationsForDotfiles_1.isDotfileMigrationNeeded)(previousConfig.metadata.cliVersion, this.config.version)) {
+            this.log(`Migrating Superblocks settings from ${previousConfig.metadata.cliVersion} to ${this.config.version}...`);
+            try {
+                const newConfig = await (0, migrationsForDotfiles_1.migrateSuperblocksMonorepoConfig)(previousConfig, {
+                    previousVersion: previousConfig.metadata.cliVersion,
+                    currentVersion: this.config.version,
+                });
+                await fs_extra_1.default.writeFile(rootConfigPath, JSON.stringify((0, version_control_1.sortByKey)(newConfig), null, 2));
+                await Promise.all(Object.entries(newConfig.resources).map(async ([, resource]) => {
+                    this.log(`Migrating ${resource.location}`);
+                    try {
+                        const resourcePath = node_path_1.default.join(rootConfigPath, "../..", resource.location, ".superblocks/superblocks.json");
+                        const resourceConfig = await fs_extra_1.default.readJSON(resourcePath);
+                        const newConfig = await (0, migrationsForDotfiles_1.migrateSuperblocksEntityConfig)(resourceConfig, {
+                            previousVersion: previousConfig
+                                .metadata.cliVersion,
+                            currentVersion: this.config.version,
+                        });
+                        await fs_extra_1.default.writeFile(resourcePath, JSON.stringify((0, version_control_1.sortByKey)(newConfig), null, 2));
+                    }
+                    catch (e) {
+                        this.error(e);
+                    }
+                }));
+                this.log(`Finalizing migration`);
+                this.log(`After upgrading the CLI version, you may need to perform additional migrations using
+${(0, colorette_1.cyan)("superblocks migrate")}`);
+            }
+            catch (e) {
+                this.error(e);
+            }
+        }
+        if (previousConfig.metadata.cliVersion) {
+            const warningMessage = (0, migrationWarningsForApplications_1.getWarningsForApplicationMigration)(previousConfig.metadata.cliVersion, this.config.version);
+            if (warningMessage) {
+                this.log(warningMessage);
+            }
+        }
+        // Always upgrade the root config even if there's no migration
+        if (rootConfigPath) {
+            previousConfig.metadata.cliVersion = this.config.version;
+            await fs_extra_1.default.writeFile(rootConfigPath, JSON.stringify((0, version_control_1.sortByKey)(previousConfig), null, 2));
+        }
+    }
 }
 exports.AuthenticatedCommand = AuthenticatedCommand;
 class AuthenticatedApplicationCommand extends AuthenticatedCommand {
@@ -52,6 +115,7 @@ class AuthenticatedApplicationCommand extends AuthenticatedCommand {
         return new URL(`/applications/${this.applicationConfig.id}/pages/${this.applicationConfig.defaultPageId}/edit`, baseUrl).toString();
     }
     async init() {
+        var _a;
         await super.init();
         try {
             this.applicationConfig = await (0, util_1.getSuperblocksApplicationConfigJson)();
@@ -61,8 +125,44 @@ class AuthenticatedApplicationCommand extends AuthenticatedCommand {
                 exit: 1,
             });
         }
+        try {
+            const appYaml = await fs_extra_1.default.readFile("application.yaml", "utf-8");
+            const appJson = await (0, yaml_1.parse)(appYaml);
+            if ((_a = appJson === null || appJson === void 0 ? void 0 : appJson.settings) === null || _a === void 0 ? void 0 : _a.cliVersion) {
+                const warningMessage = (0, migrationWarningsForApplications_1.getWarningsForApplicationMigration)(appJson.settings.cliVersion, this.config.version);
+                if (warningMessage) {
+                    this.log(warningMessage);
+                }
+            }
+        }
+        catch (e) {
+            this.warn(`Could not read page.yaml to determine version compatibility: ${e.message}`);
+        }
     }
     async registerComponents() {
+        var _a;
+        core_1.ux.action.start("Checking CLI version compatibility...");
+        try {
+            const packageJson = await fs_extra_1.default.readJson("package.json");
+            const versionStr = (_a = packageJson.dependencies) === null || _a === void 0 ? void 0 : _a["@superblocksteam/custom-components"];
+            if (!versionStr) {
+                throw new Error(`You must install the @superblocksteam/custom-components library as a dependency in your package.json file. Run:
+
+${(0, colorette_1.cyan)("superblocks migrate")}`);
+            }
+            if (!semver_1.default.satisfies(this.config.version, versionStr)) {
+                throw new Error(`You must upgrade the @superblocksteam/custom-components library. You are using ${versionStr} but the CLI is ${this.config.version}. Run:
+
+${(0, colorette_1.cyan)("superblocks migrate")}`);
+            }
+        }
+        catch (e) {
+            core_1.ux.action.stop();
+            this.error(e.message, {
+                exit: 1,
+            });
+        }
+        core_1.ux.action.stop();
         core_1.ux.action.start("Scanning for Superblocks components...");
         const exists = await fs_extra_1.default.pathExists(util_1.CUSTOM_COMPONENTS_PATH);
         if (!exists) {

package/dist/common/defaults/create-component-defaults.d.ts

@@ -1,9 +1,9 @@
-import { type StatefulProperty } from "@superblocksteam/util";
-export declare const getDefaultConfigTs: ({ id, name, displayName, statefulPropsRendered, eventHandlersRendered, }: {
+import { type Property } from "@superblocksteam/util";
+export declare const getDefaultConfigTs: ({ id, name, displayName, propertiesRendered, eventHandlersRendered, }: {
     id: string;
     name: string;
     displayName: string;
-    statefulPropsRendered: string;
+    propertiesRendered: string;
     eventHandlersRendered: string;
 }) => string;
-export declare const getDefaultComponentTsx: (statefulProps: StatefulProperty[], eventHandlers: string[]) => string;
+export declare const getDefaultComponentTsx: (properties: Property[], eventHandlers: string[]) => string;

package/dist/common/defaults/create-component-defaults.js

@@ -8,7 +8,7 @@ const indent = (str, spaces) => {
         .map((line) => `${spacesString}${line}`)
         .join("\n");
 };
-const getDefaultConfigTs = ({ id, name, displayName, statefulPropsRendered, eventHandlersRendered, }) => `import { type ComponentConfig } from "@superblocksteam/custom-components";
+const getDefaultConfigTs = ({ id, name, displayName, propertiesRendered, eventHandlersRendered, }) => `import { type ComponentConfig } from "@superblocksteam/custom-components";
 
 export default {
   // DO NOT CHANGE THE ID ONCE THE COMPONENT HAS BEEN REGISTERED!
@@ -16,20 +16,20 @@ export default {
   name: "${name}",
   displayName: "${displayName}",
   componentPath: "components/${name}/component.tsx",
-  statefulProperties: [${indent(statefulPropsRendered, 4).trim()}],
-  eventHandlers: [${indent(eventHandlersRendered, 4).trim()}],
+  properties: [${indent(propertiesRendered, 4).trim()}],
+  events: [${indent(eventHandlersRendered, 4).trim()}],
 } satisfies ComponentConfig;
 `;
 exports.getDefaultConfigTs = getDefaultConfigTs;
-const getDefaultComponentTsx = (statefulProps, eventHandlers) => `import React from "react";
+const getDefaultComponentTsx = (properties, eventHandlers) => `import React from "react";
 import { useSuperblocksContext } from "@superblocksteam/custom-components";
 import { type Props, type EventTriggers } from "./types";
 
-export default function Component({${statefulProps.length === 0
+export default function Component({${properties.length === 0
     ? ""
-    : "\n" + statefulProps.map((v) => indent(v.path, 2) + ",\n").join("")}}: Props) {
+    : "\n" + properties.map((v) => indent(v.path, 2) + ",\n").join("")}}: Props) {
   const {
-    updateStatefulProperties,
+    updateProperties,
     events: {${"\n" + eventHandlers.map((v) => indent(v, 6) + ",\n").join("")}    },
   } = useSuperblocksContext<Props, EventTriggers>();
 

package/dist/common/version-control.js

@@ -88,7 +88,7 @@ async function downloadFile(rootDirectory, filepath, url) {
     return Promise.resolve("");
 }
 async function writeResourceToDisk(resourceType, resourceId, resource, now, rootPath, existingRelativeLocation) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     switch (resourceType) {
         case "APPLICATION": {
             const parentDirName = "apps";
@@ -135,7 +135,9 @@ async function writeResourceToDisk(resourceType, resourceId, resource, now, root
             }
             await fs.ensureDir(`${appDirName}/${util_1.SUPERBLOCKS_HOME_FOLDER_NAME}`);
             await fs.writeFile(`${appDirName}/${util_1.RESOURCE_CONFIG_PATH}`, JSON.stringify(sortByKey(applicationConfig), null, 2));
-            const createdFiles = await Promise.resolve(resource.componentFiles.map((file) => downloadFile(appDirName, file.filename, file.url)));
+            const createdFiles = await Promise.resolve(
+            // Defensive check for when application settings are missing componentFiles
+            (_f = (_e = resource.componentFiles) === null || _e === void 0 ? void 0 : _e.map((file) => downloadFile(appDirName, file.filename, file.url))) !== null && _f !== void 0 ? _f : []);
             // print out failed downloads synchronously here
             createdFiles
                 .filter((createdFiles) => createdFiles.length)
@@ -149,7 +151,7 @@ async function writeResourceToDisk(resourceType, resourceId, resource, now, root
         }
         case "BACKEND": {
             const parentDirName = "backends";
-            const apiName = slugifyName((_g = (_f = (_e = resource.apiPb) === null || _e === void 0 ? void 0 : _e.metadata) === null || _f === void 0 ? void 0 : _f.name) !== null && _g !== void 0 ? _g : resource.actions.name);
+            const apiName = slugifyName((_j = (_h = (_g = resource.apiPb) === null || _g === void 0 ? void 0 : _g.metadata) === null || _h === void 0 ? void 0 : _h.name) !== null && _j !== void 0 ? _j : resource.actions.name);
             // server is still sending actions for a backwards compatibility
             delete resource.actions;
             const newRelativeLocation = `${parentDirName}/${apiName}`;

package/dist/util/migrationWarningsForApplications.d.ts

@@ -0,0 +1 @@
+export declare function getWarningsForApplicationMigration(previousVersion: string, newVersion: string): string | undefined;

package/dist/util/migrationWarningsForApplications.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWarningsForApplicationMigration = void 0;
+const tslib_1 = require("tslib");
+const colorette_1 = require("colorette");
+const semver_1 = tslib_1.__importDefault(require("semver"));
+// If you are changing how application files work on disk, for example changing the directory layout,
+// you need to tell the user how to upgrade manually.
+const BREAKING_APPLICATION_VERSIONS = [
+    {
+        version: "0.0.20",
+        // This is an example message because 0.0.20 does not have a docs page for any migrations. This will be added
+        // in a future release
+        message: `${(0, colorette_1.red)("Warning")}: Your code must be updated due to a breaking change in custom component definitions. See docs.`,
+    },
+    {
+        version: "0.0.21",
+        // This is an example message because 0.0.21 does not have a docs page for any migrations. This will be added
+        // in a future release
+        message: `${(0, colorette_1.red)("Warning")}: You will not be able to use CLI commands on custom components until you manually migrate your components,
+due to breaking changes in the config.ts format and custom component API.
+    
+${(0, colorette_1.bold)("Your existing components are safe.")}
+
+To manually migrate:
+
+1. Rename "eventHandlers" to "events".
+2. Update your properties to use the new format: ${(0, colorette_1.magenta)("https://docs.superblocks.com/applications/custom-components/development-lifecycle#configts")}
+`,
+    },
+];
+function getWarningsForApplicationMigration(previousVersion, newVersion) {
+    const firstBreakingChange = BREAKING_APPLICATION_VERSIONS.find(({ version }) => {
+        return (semver_1.default.lt(previousVersion, version) && semver_1.default.lte(version, newVersion));
+    });
+    return firstBreakingChange === null || firstBreakingChange === void 0 ? void 0 : firstBreakingChange.message;
+}
+exports.getWarningsForApplicationMigration = getWarningsForApplicationMigration;

package/dist/util/migrationsForDotfiles.d.ts

@@ -0,0 +1,10 @@
+import { SuperblocksApplicationConfig, SuperblocksBackendConfig, SuperblocksMonorepoConfig } from "@superblocksteam/util";
+export declare function migrateSuperblocksMonorepoConfig(config: SuperblocksMonorepoConfig, options: {
+    previousVersion: string;
+    currentVersion: string;
+}): Promise<SuperblocksMonorepoConfig>;
+export declare function migrateSuperblocksEntityConfig(config: SuperblocksApplicationConfig | SuperblocksBackendConfig, options: {
+    previousVersion: string;
+    currentVersion: string;
+}): Promise<SuperblocksApplicationConfig | SuperblocksBackendConfig>;
+export declare function isDotfileMigrationNeeded(previousVersion: string, currentVersion: string): boolean;

package/dist/util/migrationsForDotfiles.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDotfileMigrationNeeded = exports.migrateSuperblocksEntityConfig = exports.migrateSuperblocksMonorepoConfig = void 0;
+const tslib_1 = require("tslib");
+const semver_1 = tslib_1.__importDefault(require("semver"));
+// These migrations are used to upgrade the Superblocks config files as needed.
+// For example if we add a new required field
+const MonorepoMigratorsFromOldVersion = [
+    {
+        migrateWhenUpgradingTo: "0.0.19",
+        migrator: (config) => config,
+    },
+];
+// Recursively migrate configs to the latest version
+async function migrateSuperblocksMonorepoConfig(config, options) {
+    return await sharedMigrator(MonorepoMigratorsFromOldVersion, config, options);
+}
+exports.migrateSuperblocksMonorepoConfig = migrateSuperblocksMonorepoConfig;
+// These migrations are used to upgrade the Superblocks config files as needed.
+// For example if we add a new required field
+const EntityMigratorsFromOldVersion = [
+    {
+        migrateWhenUpgradingTo: "0.0.19",
+        migrator: (config) => config,
+    },
+];
+async function migrateSuperblocksEntityConfig(config, options) {
+    return await sharedMigrator(EntityMigratorsFromOldVersion, config, options);
+}
+exports.migrateSuperblocksEntityConfig = migrateSuperblocksEntityConfig;
+function isDotfileMigrationNeeded(previousVersion, currentVersion) {
+    return (previousVersion !== currentVersion &&
+        (MonorepoMigratorsFromOldVersion.some(({ migrateWhenUpgradingTo }) => semver_1.default.gt(migrateWhenUpgradingTo, previousVersion) &&
+            semver_1.default.lte(migrateWhenUpgradingTo, currentVersion)) ||
+            EntityMigratorsFromOldVersion.some(({ migrateWhenUpgradingTo }) => semver_1.default.gt(migrateWhenUpgradingTo, previousVersion) &&
+                semver_1.default.lte(migrateWhenUpgradingTo, currentVersion))));
+}
+exports.isDotfileMigrationNeeded = isDotfileMigrationNeeded;
+async function sharedMigrator(migratorObject, config, { previousVersion, currentVersion, }) {
+    let newConfig = JSON.parse(JSON.stringify(config));
+    // Find all migrators in the range between previousVersion and currentVersion
+    const migratorFns = migratorObject.filter(({ migrateWhenUpgradingTo }) => semver_1.default.gt(migrateWhenUpgradingTo, previousVersion) &&
+        semver_1.default.lte(migrateWhenUpgradingTo, currentVersion));
+    migratorFns.forEach(({ migrator, migrateWhenUpgradingTo }) => {
+        try {
+            newConfig = migrator(newConfig);
+        }
+        catch (e) {
+            // Migrations fail if our preconditions aren't met
+            console.warn(`Error while migrating config to version ${migrateWhenUpgradingTo}: ${e.message}`);
+            throw e;
+        }
+    });
+    return newConfig;
+}

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.20",
+  "version": "0.0.21",
   "commands": {
     "init": {
       "id": "init",
@@ -37,7 +37,7 @@
     },
     "login": {
       "id": "login",
-      "description": "Authenticates with Superblocks cloud",
+      "description": "Authenticate with Superblocks cloud",
       "strict": true,
       "pluginName": "@superblocksteam/cli",
       "pluginAlias": "@superblocksteam/cli",
@@ -54,6 +54,20 @@
       },
       "args": {}
     },
+    "migrate": {
+      "id": "migrate",
+      "description": "Migrate files to use the current CLI version",
+      "strict": true,
+      "pluginName": "@superblocksteam/cli",
+      "pluginAlias": "@superblocksteam/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "args": {}
+    },
     "pull": {
       "id": "pull",
       "description": "Download objects from Superblocks and save them locally",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/cli",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "Official Superblocks CLI",
   "bin": {
     "superblocks": "bin/run"
@@ -29,6 +29,7 @@
     "fs-extra": "^11.1.1",
     "listr2": "6.6.0",
     "lodash": "^4.17.21",
+    "semver": "^7.5.4",
     "slugify": "^1.6.6",
     "vite": "^4.4.8",
     "vite-plugin-inspect": "^0.7.28",