@superblocksteam/cli 0.0.19 → 0.0.21

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/commands/pull.js

@@ -87,20 +87,12 @@ class Pull extends authenticated_command_1.AuthenticatedCommand {
             {
                 title: "Updating Superblocks project file...",
                 task: async (ctx) => {
-                    var _a;
-                    const superblocksRootConfig = {
-                        configType: "ROOT",
-                        resources: ctx.existingSuperblocksRootConfig.resources,
-                        metadata: {
-                            ...(_a = ctx.existingSuperblocksRootConfig) === null || _a === void 0 ? void 0 : _a.metadata,
-                            lastUpdated: ctx.now,
-                        },
-                    };
+                    const [superblocksRootConfig, rootConfigPath] = await (0, util_1.getSuperblocksMonorepoConfigJson)(true);
                     for (const [resourceId, resource] of Object.entries(ctx.writtenResources)) {
                         superblocksRootConfig.resources[resourceId] = resource;
                     }
                     // update superblocks.json file
-                    await fs.writeFile(ctx.superblocksRootConfigPath, JSON.stringify((0, version_control_1.sortByKey)(superblocksRootConfig), null, 2));
+                    await fs.writeFile(rootConfigPath, JSON.stringify((0, version_control_1.sortByKey)(superblocksRootConfig), null, 2));
                 },
             },
         ], {
@@ -128,7 +120,7 @@ class Pull extends authenticated_command_1.AuthenticatedCommand {
         for (const [resourceId, resource] of Object.entries((_f = (_e = ctx.existingSuperblocksRootConfig) === null || _e === void 0 ? void 0 : _e.resources) !== null && _f !== void 0 ? _f : {})) {
             choices.push({
                 name: resourceId,
-                message: `${resource.location} (Last updated at ${new Date(resource.lastUpdated).toLocaleTimeString()})`,
+                message: resource.location,
             });
             if (((_g = ctx.existingSuperblocksResourceConfig) === null || _g === void 0 ? void 0 : _g.id) === resourceId) {
                 initialSelections.push(counter);

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,8 +23,10 @@ class AuthenticatedCommand extends core_1.Command {
             }
             const { token, superblocksBaseUrl } = result;
             this.sdk = new sdk_1.SuperblocksSdk(token, superblocksBaseUrl);
+            await this.runAutomatedDotfileUpdates();
         }
-        catch {
+        catch (e) {
+            console.log(e.message);
             this.error("Please run 'superblocks login' first", { exit: 1 });
         }
     }
@@ -32,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 {
@@ -50,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)();
@@ -59,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 { StatefulProperty } from "../types";
-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/cli";
+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,21 +16,23 @@ 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";
-import { Props } from "./types";
+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({${properties.length === 0
+    ? ""
+    : "\n" + properties.map((v) => indent(v.path, 2) + ",\n").join("")}}: Props) {
+  const {
+    updateProperties,
+    events: {${"\n" + eventHandlers.map((v) => indent(v, 6) + ",\n").join("")}    },
+  } = useSuperblocksContext<Props, EventTriggers>();
 
-export default function Component({
-  updateStatefulProperties${statefulProps.length > 0
-    ? ",\n" + statefulProps.map((v) => indent(v.path, 2)).join(",\n")
-    : ""}${eventHandlers.length > 0
-    ? ",\n" + eventHandlers.map((v) => indent(v, 2)).join(",\n")
-    : ""}
-}: Props) {
   return (
     <div
       style={{

package/dist/common/version-control.d.ts

@@ -1,11 +1,5 @@
 import { ViewMode } from "@superblocksteam/sdk";
 import { VersionedResourceConfig } from "@superblocksteam/util";
-export type SuperblocksMetadata = {
-    cliVersion: string;
-    remote: string;
-    lastUpdated: number;
-    created: number;
-};
 export declare const LATEST_EDITS_MODE = "latest-edits";
 export declare const MOST_RECENT_COMMIT_MODE = "most-recent-commit";
 export declare const DEPLOYED_MODE = "deployed";

package/dist/common/version-control.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sortByKey = exports.getMode = exports.writeResourceToDisk = exports.atLeastOneSelection = exports.MULTI_SELECT_PROMPT_HELP = exports.SELECT_PROMPT_HELP = exports.modeFlagToViewMode = exports.modeFlagValuesMap = exports.DEPLOYED_MODE = exports.MOST_RECENT_COMMIT_MODE = exports.LATEST_EDITS_MODE = void 0;
 const tslib_1 = require("tslib");
+const https = tslib_1.__importStar(require("https"));
 const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const path_1 = require("path");
 const util_1 = require("@superblocksteam/util");
 const colorette_1 = require("colorette");
 const fs = tslib_1.__importStar(require("fs-extra"));
@@ -46,8 +48,47 @@ function slugifyName(originalName) {
         lower: true,
     });
 }
+// resolves a true promise when download is complete. If there's an error, resolve false
+async function downloadFile(rootDirectory, filepath, url) {
+    const fullPath = `${rootDirectory}/${filepath}`;
+    // eslint-disable-next-line no-async-promise-executor
+    const result = await new Promise(async (resolve) => {
+        try {
+            // create directory path if it doesn't exist yet
+            if (!(await fs.pathExists(fullPath))) {
+                await fs.mkdir((0, path_1.dirname)(fullPath), { recursive: true });
+            }
+            const file = fs.createWriteStream(fullPath);
+            https.get(url, (resp) => {
+                resp.pipe(file);
+                file
+                    .on("finish", () => {
+                    file.end(() => resolve(true));
+                })
+                    .on("error", () => {
+                    fs.unlink(filepath);
+                    resolve(false);
+                });
+            });
+        }
+        catch (e) {
+            return resolve(false);
+        }
+    });
+    // failed to download correctly, attempt to clean up file
+    if (!result) {
+        try {
+            await fs.unlink(fullPath);
+        }
+        catch (e) {
+            console.log("Failed to delete file", fullPath);
+        }
+        return Promise.resolve(fullPath);
+    }
+    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";
@@ -94,15 +135,23 @@ 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(
+            // 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)
+                .forEach((createdFile) => {
+                console.log(`Unable to download ${createdFile}`);
+            });
             return {
                 location: relativeLocation,
-                lastUpdated: now,
                 resourceType: "APPLICATION",
             };
         }
         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}`;
@@ -123,7 +172,6 @@ async function writeResourceToDisk(resourceType, resourceId, resource, now, root
             await fs.writeFile(`${backendDirName}/${util_1.RESOURCE_CONFIG_PATH}`, JSON.stringify(sortByKey(backendConfig), null, 2));
             return {
                 location: relativeLocation,
-                lastUpdated: now,
                 resourceType: "BACKEND",
             };
         }

package/dist/index.d.ts

@@ -1,2 +1 @@
 export { run } from "@oclif/core";
-export * from "./exportedTypes";

package/dist/index.js

@@ -1,7 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.run = void 0;
-const tslib_1 = require("tslib");
 var core_1 = require("@oclif/core");
 Object.defineProperty(exports, "run", { enumerable: true, get: function () { return core_1.run; } });
-tslib_1.__exportStar(require("./exportedTypes"), exports);

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.19",
+  "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",