@superblocksteam/sdk 1.14.2 → 2.0.3-next.46

package/src/version-control.mts

@@ -0,0 +1,1351 @@
+import * as https from "https";
+import path from "node:path";
+import { dirname } from "path";
+import { ExportViewMode } from "@superblocksteam/shared";
+import {
+  RESOURCE_CONFIG_PATH,
+  SUPERBLOCKS_HOME_FOLDER_NAME,
+  getSuperblocksApplicationConfigIfExists,
+  getSuperblocksApplicationConfigJson,
+  getSuperblocksBackendConfigIfExists,
+  getSuperblocksApplicationV2ConfigJson,
+  readAppApiYamlFile,
+  writeApiFiles,
+  DEFAULT_LINES_FOR_LARGE_STEPS,
+} from "@superblocksteam/util";
+import { bold } from "colorette";
+import fs from "fs-extra";
+import { isEmpty, isArray, isObject, get } from "lodash-es";
+import * as semver from "semver";
+import { simpleGit } from "simple-git";
+import slugify from "slugify";
+import { parse, stringify as ymlstringify } from "yaml";
+import type {
+  ApplicationWrapper,
+  MultiPageApplicationWrapper,
+  MultiPageApplicationWrapperWithComponents,
+  CodeModeApplicationWrapper,
+} from "./client.js";
+import type { FeatureFlags } from "./flag.js";
+import type { SuperblocksSdk } from "./sdk.js";
+import type { ApiWithPb, Page } from "./types/index.js";
+import type {
+  LocalGitRepoState,
+  SuperblocksBackendConfig,
+  SuperblocksMonorepoConfig,
+  SuperblocksApplicationConfig,
+  SuperblocksResourceConfig,
+  SuperblocksResourceConfigMetadata,
+  VersionedResourceConfig,
+  ApiInfo,
+  PageInfo,
+  SuperblocksApplicationV2Config,
+  ApiWrapper,
+  AdditionalStepFiles,
+} from "@superblocksteam/util";
+import type { SimpleGit, StatusResult } from "simple-git";
+
+export const LATEST_EDITS_MODE = "latest-edits";
+export const MOST_RECENT_COMMIT_MODE = "most-recent-commit";
+export const DEPLOYED_MODE = "deployed";
+
+export const DEFAULT_BRANCH = "main";
+
+export const modeFlagValuesMap: Record<string, string> = {
+  [LATEST_EDITS_MODE]: "Latest edits",
+  [MOST_RECENT_COMMIT_MODE]: "Most recent commit",
+  [DEPLOYED_MODE]: "Deployed",
+};
+
+export enum FileStructureType {
+  SINGLE_PAGE = "single-page",
+  MULTI_PAGE = "multi-page",
+}
+
+export function modeFlagToViewMode(modeFlag: ModeFlag): ExportViewMode {
+  switch (modeFlag) {
+    case LATEST_EDITS_MODE:
+      return ExportViewMode.EXPORT_LIVE;
+    case MOST_RECENT_COMMIT_MODE:
+      return ExportViewMode.EXPORT_LATEST;
+    case DEPLOYED_MODE:
+      return ExportViewMode.EXPORT_DEPLOYED;
+    default:
+      throw new Error(`Unsupported mode flag: ${modeFlag}`);
+  }
+}
+
+export type ModeFlag = (keyof typeof modeFlagValuesMap)[number];
+
+export const SELECT_PROMPT_HELP = "Use ↑/↓ arrow keys, Enter to confirm";
+export const MULTI_SELECT_PROMPT_HELP =
+  "Type to filter, Use ↑/↓ arrow keys, Space to select, Enter to confirm";
+
+export const atLeastOneSelection = (value: string[]) => {
+  if (isEmpty(value)) {
+    return `Please select at least one item ${bold("by pressing space")}`;
+  }
+
+  return true;
+};
+
+export type ApiRepresentation = {
+  extractLargeSourceFiles: boolean;
+  minLinesForExtraction: number;
+};
+
+const DEFAULT_FILE_VERSION = "0.1.0";
+const SPLIT_LARGE_API_STEPS_VERSION = "0.2.0";
+const LATEST_FILE_VERSION = SPLIT_LARGE_API_STEPS_VERSION;
+
+export function getApiRepresentation(
+  featureFlags: FeatureFlags,
+  resourceConfig: SuperblocksResourceConfig,
+): ApiRepresentation {
+  const linesForLargeSteps =
+    featureFlags.linesForLargeSteps() ?? DEFAULT_LINES_FOR_LARGE_STEPS;
+  if (
+    featureFlags.splitLargeApiStepsEnabled() &&
+    isPostSplitLargeApiSteps(resourceConfig)
+  ) {
+    return {
+      extractLargeSourceFiles: true,
+      minLinesForExtraction: linesForLargeSteps,
+    };
+  }
+  // Return the default
+  return {
+    extractLargeSourceFiles: false,
+    minLinesForExtraction: linesForLargeSteps,
+  };
+}
+
+function isPostSplitLargeApiSteps(
+  resourceConfig: SuperblocksResourceConfig | undefined,
+) {
+  if (!resourceConfig) {
+    return false;
+  }
+  const version = resourceConfig.metadata?.fileVersion ?? DEFAULT_FILE_VERSION;
+  return semver.compare(version, SPLIT_LARGE_API_STEPS_VERSION) >= 0;
+}
+
+function slugifyName(originalName: any): string {
+  return (slugify as any)(originalName, {
+    replacement: "_",
+    lower: true,
+  });
+}
+
+// resolves a true promise when download is complete. If there's an error, resolve false
+async function downloadFile(
+  rootDirectory: string,
+  filepath: string,
+  url: string,
+): Promise<string> {
+  const fullPath = `${rootDirectory}/${filepath}`;
+  // eslint-disable-next-line no-async-promise-executor
+  const result = await new Promise<boolean>(async (resolve) => {
+    try {
+      // create directory path if it doesn't exist yet
+      if (!(await fs.pathExists(fullPath))) {
+        await fs.mkdir(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 {
+      return resolve(false);
+    }
+  });
+
+  // failed to download correctly, attempt to clean up file
+  if (!result) {
+    try {
+      await fs.unlink(fullPath);
+    } catch {
+      console.log("Failed to delete file", fullPath);
+    }
+
+    return Promise.resolve(fullPath);
+  }
+  return Promise.resolve("");
+}
+
+async function readYamlFile(path: string): Promise<any> {
+  return parse(await fs.readFile(path, "utf8"));
+}
+
+function getFileStructureTypeFromResourceConfig(
+  superblocksConfig: SuperblocksApplicationConfig,
+) {
+  if (superblocksConfig.pages) {
+    return FileStructureType.MULTI_PAGE;
+  }
+  return FileStructureType.SINGLE_PAGE;
+}
+
+export async function getFileStructureType(
+  rootPath: string,
+  existingRelativeLocation: string,
+): Promise<FileStructureType> {
+  try {
+    const superblocksConfig = await getSuperblocksApplicationConfigJson(
+      `${rootPath}/${existingRelativeLocation}`,
+    );
+    return getFileStructureTypeFromResourceConfig(superblocksConfig);
+  } catch {
+    await getSuperblocksApplicationV2ConfigJson(
+      `${rootPath}/${existingRelativeLocation}`,
+    );
+    return FileStructureType.MULTI_PAGE;
+  }
+}
+
+// NOTE: If a change is made to how applications are read from disk, please update
+// logic to write applications to disk in the "writeResourceToDisk" function accordingly.
+// @deprecated this can be removed once all customers move to multi page applications
+export async function readApplicationFromDisk(
+  rootPath: string,
+  existingRelativeLocation: string,
+): Promise<ApplicationWrapper> {
+  const application = await readYamlFile(
+    `${rootPath}/${existingRelativeLocation}/application.yaml`,
+  );
+
+  const page = await readYamlFile(
+    `${rootPath}/${existingRelativeLocation}/page.yaml`,
+  );
+
+  const apisDirName = `${rootPath}/${existingRelativeLocation}/apis`;
+  const apis: any[] = [];
+
+  if (await fs.pathExists(apisDirName)) {
+    const apiFiles = await fs.readdir(apisDirName);
+    for (const apiFile of apiFiles) {
+      const { api: apiContent } = await readAppApiYamlFile(
+        apisDirName,
+        apiFile,
+      );
+      // This mimics the shape of the ApiV3Dto object
+      apis.push({
+        id: apiContent.metadata.id,
+        apiPb: apiContent,
+      });
+    }
+  }
+
+  return {
+    application,
+    apis,
+    page,
+  };
+}
+
+// NOTE: If a change is made to how applications are read from disk, please update
+// logic to write applications to disk in the "writeResourceToDisk" function accordingly.
+export async function readMultiPageApplicationFromDisk(
+  rootPath: string,
+  existingRelativeLocation: string,
+): Promise<MultiPageApplicationWrapper> {
+  const superblocksApplicationConfig =
+    await getSuperblocksApplicationConfigJson(
+      `${rootPath}/${existingRelativeLocation}`,
+    );
+  const application = await readYamlFile(
+    `${rootPath}/${existingRelativeLocation}/application.yaml`,
+  );
+
+  const pagesDirName = `${rootPath}/${existingRelativeLocation}/pages`;
+  const pages: Page[] = [];
+
+  if (await fs.pathExists(pagesDirName)) {
+    for (const page of Object.values(
+      superblocksApplicationConfig.pages ?? {},
+    )) {
+      // Read in the page definition
+      const pageContent = await readYamlFile(
+        `${pagesDirName}/${slugifyName(page.name)}/page.yaml`,
+      );
+
+      // Read in the API definitions for this page
+      const pageApisDirName = `${pagesDirName}/${slugifyName(page.name)}/apis`;
+      const apis: ApiWithPb[] = [];
+
+      if (await fs.pathExists(pageApisDirName)) {
+        // Get the API names from pageApis if it exists, or from apis if it doesn't
+        const pageApiNames = getApiNamesFromPageConfig(page);
+        for (const apiName of pageApiNames) {
+          const { api: apiContent } = await readAppApiYamlFile(
+            pageApisDirName,
+            apiName,
+          );
+          // This mimics the shape of the ApiV3Dto object
+          apis.push({
+            id: apiContent.metadata.id,
+            pageId: page.id, // Alternatively, pageId is also stored in apiPb.trigger.application.pageId
+            apiPb: apiContent,
+          });
+        }
+      }
+      pages.push({
+        id: pageContent.id,
+        name: pageContent.name,
+        applicationId: pageContent.applicationId,
+        isHidden: pageContent.isHidden,
+        layouts: pageContent.layouts,
+        apis,
+      });
+    }
+  }
+
+  const appApisDirName = `${rootPath}/${existingRelativeLocation}/apis`;
+  const apis: any[] = [];
+
+  if (await fs.pathExists(appApisDirName)) {
+    // Get the API names from appApis if it exists, or from apis if it doesn't
+    const appConfig = superblocksApplicationConfig;
+    const apiNames = getApiNamesFromApplicationConfig(appConfig);
+    for (const apiName of apiNames) {
+      const { api: apiContent } = await readAppApiYamlFile(
+        appApisDirName,
+        apiName,
+      );
+      // This mimics the shape of the ApiV3Dto object
+      apis.push({
+        id: apiContent.metadata.id,
+        apiPb: apiContent,
+      });
+    }
+  }
+
+  return {
+    application,
+    apis,
+    pages,
+  };
+}
+
+function getApiNamesFromApplicationConfig(
+  applicationConfig: SuperblocksApplicationConfig,
+): string[] {
+  return applicationConfig.appApis
+    ? Object.values(applicationConfig.appApis).map((api) => api.name)
+    : Object.values(applicationConfig.apis ?? {});
+}
+
+function getApiNamesFromPageConfig(pageConfig: PageInfo): string[] {
+  return pageConfig.pageApis
+    ? Object.values(pageConfig.pageApis).map((api) => api.name)
+    : Object.values(pageConfig.apis ?? {});
+}
+
+export async function readApiFromDisk(
+  rootPath: string,
+  existingRelativeLocation: string,
+): Promise<ApiWrapper> {
+  const path = `${rootPath}/${existingRelativeLocation}`;
+  const { api: apiContent } = await readAppApiYamlFile(path);
+  return {
+    apiPb: apiContent,
+  };
+}
+
+// NOTE: If a change is made to how applications are written to disk, please update
+// logic to read applications from disk in the "readApplicationFromDisk" function accordingly.
+export async function writeResourceToDisk(
+  resourceType: string,
+  resourceId: string,
+  resource: any,
+  rootPath: string,
+  featureFlags: FeatureFlags,
+  existingRelativeLocation?: string,
+  preferredApiRepresentation?: ApiRepresentation,
+): Promise<VersionedResourceConfig> {
+  switch (resourceType) {
+    case "APPLICATION": {
+      const parentDirName = "apps";
+      const newRelativeLocation = `${parentDirName}/${slugifyName(
+        resource.application.name,
+      )}`;
+      const relativeLocation = existingRelativeLocation ?? newRelativeLocation;
+      const appDirName = path.resolve(rootPath, relativeLocation);
+      if (!(await fs.pathExists(appDirName))) {
+        await fs.mkdir(appDirName, { recursive: true });
+      }
+
+      const applicationContent = ymlstringify(resource.application, {
+        sortMapEntries: true,
+      });
+      await fs.outputFile(`${appDirName}/application.yaml`, applicationContent);
+      if (resource.page) {
+        const pageContent = ymlstringify(resource.page, {
+          sortMapEntries: true,
+          blockQuote: "literal",
+        });
+        await fs.outputFile(`${appDirName}/page.yaml`, pageContent);
+      }
+
+      const apiPromises: Array<Promise<void>> = [];
+      const apisDirName = `${appDirName}/apis`;
+      await fs.ensureDir(apisDirName);
+
+      const existingApplicationConfig =
+        await getSuperblocksApplicationConfigIfExists(appDirName);
+      const existingFilePaths = getExistingFilePathsForApplicationApi(
+        existingApplicationConfig,
+        appDirName,
+      );
+
+      const newApplicationConfig: SuperblocksApplicationConfig = {
+        configType: "APPLICATION",
+        defaultPageId: resource.page?.id,
+        id: resource.application.id,
+        metadata: getResourceConfigMetadata(
+          featureFlags,
+          existingApplicationConfig,
+        ),
+      };
+
+      const apiRepresentation =
+        preferredApiRepresentation ??
+        getApiRepresentation(featureFlags, newApplicationConfig);
+
+      if (resource.apis) {
+        for (const api of resource.apis as ApiWrapper[]) {
+          const apiInfo = await writeAppApi(
+            api,
+            appDirName,
+            existingFilePaths,
+            apiPromises,
+            apiRepresentation,
+          );
+          if (apiRepresentation.extractLargeSourceFiles) {
+            if (!newApplicationConfig.appApis) {
+              newApplicationConfig.appApis = {};
+            }
+            newApplicationConfig.appApis[api.apiPb.metadata.id] = apiInfo;
+          } else {
+            if (!newApplicationConfig.apis) {
+              newApplicationConfig.apis = {};
+            }
+            newApplicationConfig.apis[api.apiPb.metadata.id] = apiInfo.name;
+          }
+        }
+
+        await Promise.all(apiPromises);
+      }
+
+      // Delete any existing files that were not overwritten
+      for (const filePath of existingFilePaths) {
+        await fs.remove(filePath);
+      }
+
+      await fs.ensureDir(`${appDirName}/${SUPERBLOCKS_HOME_FOLDER_NAME}`);
+
+      await fs.writeFile(
+        `${appDirName}/${RESOURCE_CONFIG_PATH}`,
+        JSON.stringify(sortByKey(newApplicationConfig), null, 2),
+      );
+
+      const createdFiles = await Promise.resolve<string[]>(
+        // Defensive check for when application settings are missing componentFiles
+        resource.componentFiles?.map(
+          (file: { filename: string; url: string }) =>
+            downloadFile(appDirName, file.filename, file.url),
+        ) ?? [],
+      );
+
+      // print out failed downloads synchronously here
+      createdFiles
+        .filter((createdFiles) => createdFiles.length)
+        .forEach((createdFile) => {
+          console.log(`Unable to download ${createdFile}`);
+        });
+
+      return {
+        location: relativeLocation,
+        resourceType: "APPLICATION",
+      };
+    }
+
+    case "BACKEND": {
+      const parentDirName = "backends";
+      const apiName = slugifyName(extractApiName(resource));
+      const newRelativeLocation = `${parentDirName}/${apiName}`;
+      const relativeLocation = existingRelativeLocation ?? newRelativeLocation;
+      const backendDirName = path.resolve(rootPath, relativeLocation);
+      if (!(await fs.pathExists(backendDirName))) {
+        await fs.mkdir(backendDirName, { recursive: true });
+      }
+
+      const existingBackendConfig =
+        await getSuperblocksBackendConfigIfExists(backendDirName);
+      const existingFilePaths = getExistingFilePathsForBackendApi(
+        existingBackendConfig,
+        backendDirName,
+      );
+      const backendConfig: SuperblocksBackendConfig = {
+        id: resourceId,
+        configType: "BACKEND",
+        metadata: getResourceConfigMetadata(
+          featureFlags,
+          existingBackendConfig,
+        ),
+      };
+
+      const apiRepresentation =
+        preferredApiRepresentation ??
+        getApiRepresentation(featureFlags, backendConfig);
+
+      // Write the API file(s)
+      const apiInfo = await writeBackendApi(
+        resource,
+        backendDirName,
+        [],
+        apiRepresentation,
+        existingFilePaths,
+      );
+      if (apiRepresentation.extractLargeSourceFiles) {
+        backendConfig.sourceFiles = apiInfo.sourceFiles;
+      }
+
+      // Write the backend config file
+      await fs.ensureDir(`${backendDirName}/${SUPERBLOCKS_HOME_FOLDER_NAME}`);
+      await fs.writeFile(
+        `${backendDirName}/${RESOURCE_CONFIG_PATH}`,
+        JSON.stringify(sortByKey(backendConfig), null, 2),
+      );
+
+      // Delete any existing files that were not overwritten
+      for (const filePath of existingFilePaths) {
+        await fs.remove(filePath);
+      }
+
+      return {
+        location: relativeLocation,
+        resourceType: "BACKEND",
+      };
+    }
+
+    default: {
+      throw new Error(`Unsupported resource type: ${resourceType}`);
+    }
+  }
+}
+
+// NOTE: If a change is made to how applications are written to disk, please update
+// logic to read applications from disk in the "readMultiPageApplicationFromDisk" function accordingly.
+export async function writeApplicationToDisk({
+  sdk,
+  resource,
+  projectRootFolder,
+  appRelativePath,
+  featureFlags,
+  migrateFromSinglePage,
+  preferredApiRepresentation,
+}: {
+  sdk: SuperblocksSdk;
+  resource:
+    | MultiPageApplicationWrapperWithComponents
+    | CodeModeApplicationWrapper;
+  projectRootFolder: string;
+  appRelativePath?: string;
+  featureFlags: FeatureFlags;
+  migrateFromSinglePage?: boolean;
+  preferredApiRepresentation?: ApiRepresentation;
+}): Promise<VersionedResourceConfig> {
+  const parentDirName = "apps";
+  const newRelativeLocation = `${parentDirName}/${slugifyName(
+    resource.application.name,
+  )}`;
+  const relativeLocation = appRelativePath ?? newRelativeLocation;
+  const appDirName = path.resolve(projectRootFolder, relativeLocation);
+  if (!(await fs.pathExists(appDirName))) {
+    await fs.mkdir(appDirName, { recursive: true });
+  }
+
+  if (resource.type === "code-mode") {
+    await writeCodeModeApplicationToDisk(
+      sdk,
+      resource,
+      appDirName,
+      featureFlags,
+    );
+    return {
+      location: relativeLocation,
+      resourceType: "APPLICATION" as const,
+    };
+  } else {
+    return await writeV1ApplicationToDisk(
+      resource,
+      appDirName,
+      featureFlags,
+      relativeLocation,
+      migrateFromSinglePage,
+      preferredApiRepresentation,
+    );
+  }
+}
+
+async function writeV1ApplicationToDisk(
+  resource: MultiPageApplicationWrapperWithComponents,
+  appDirName: string,
+  featureFlags: FeatureFlags,
+  relativeLocation: string,
+  migrateFromSinglePage?: boolean,
+  preferredApiRepresentation?: ApiRepresentation,
+) {
+  const applicationContent = ymlstringify(resource.application, {
+    sortMapEntries: true,
+  });
+  await fs.outputFile(`${appDirName}/application.yaml`, applicationContent);
+
+  // Find the existing application config and existing file paths
+  const existingApplicationConfig =
+    await getSuperblocksApplicationConfigIfExists(appDirName);
+  const existingFilePaths = getExistingFilePathsForApplicationApi(
+    existingApplicationConfig,
+    appDirName,
+  );
+
+  const newApplicationConfig: SuperblocksApplicationConfig = {
+    configType: "APPLICATION",
+    id: resource.application.id,
+    metadata: getResourceConfigMetadata(
+      featureFlags,
+      existingApplicationConfig,
+    ),
+  };
+
+  const apiRepresentation =
+    preferredApiRepresentation ??
+    getApiRepresentation(featureFlags, newApplicationConfig);
+
+  newApplicationConfig.pages = {};
+
+  const apiPromises: Array<Promise<void>> = [];
+
+  for (const page of Object.values(resource.pages)) {
+    const pageId = page.id;
+    const pageDirName = `${appDirName}/pages/${slugifyName(page.name)}`;
+    if (!(await fs.pathExists(pageDirName))) {
+      await fs.mkdir(pageDirName, { recursive: true });
+    }
+    newApplicationConfig.pages[pageId] = {
+      id: page.id,
+      name: page.name,
+    };
+    const pageConfig = newApplicationConfig.pages[pageId];
+
+    const pageContent = ymlstringify(
+      {
+        id: page.id,
+        name: page.name,
+        applicationId: page.applicationId,
+        isHidden: page.isHidden,
+        layouts: page.layouts,
+      },
+      {
+        sortMapEntries: true,
+        blockQuote: "literal",
+      },
+    );
+    const pageFilePath = `${pageDirName}/page.yaml`;
+    await fs.outputFile(pageFilePath, pageContent);
+    existingFilePaths.delete(pageFilePath);
+    for (const api of page.apis as ApiWrapper[]) {
+      const apiInfo = await writeAppApi(
+        api,
+        pageDirName,
+        existingFilePaths,
+        apiPromises,
+        apiRepresentation,
+      );
+      // Update the page config with the new api info
+      const apiId = api.apiPb.metadata.id;
+      if (apiRepresentation.extractLargeSourceFiles) {
+        // Add the new pageApis field whenever large source files might be extracted
+        if (!pageConfig.pageApis) {
+          pageConfig.pageApis = {};
+        }
+        pageConfig.pageApis[apiId] = {
+          name: apiInfo.name,
+          sourceFiles: apiInfo.sourceFiles?.sort(),
+        };
+      } else {
+        if (!pageConfig.apis) {
+          pageConfig.apis = {};
+        }
+        pageConfig.apis[apiId] = apiInfo.name;
+      }
+    }
+  }
+
+  const appApis: Record<string, ApiInfo> = {};
+  if (resource.apis && resource.apis.length) {
+    for (const api of resource.apis as ApiWrapper[]) {
+      const apiInfo = await writeAppApi(
+        api,
+        appDirName,
+        existingFilePaths,
+        apiPromises,
+        apiRepresentation,
+      );
+      const apiId = api.apiPb.metadata.id;
+      if (apiRepresentation.extractLargeSourceFiles) {
+        if (!newApplicationConfig.appApis) {
+          newApplicationConfig.appApis = {};
+        }
+        newApplicationConfig.appApis[apiId] = apiInfo;
+      } else {
+        if (!newApplicationConfig.apis) {
+          newApplicationConfig.apis = {};
+        }
+        newApplicationConfig.apis[apiId] = apiInfo.name;
+      }
+    }
+    await Promise.all(apiPromises);
+  }
+  if (apiRepresentation.extractLargeSourceFiles) {
+    newApplicationConfig.appApis = appApis;
+  } else if (!newApplicationConfig.apis) {
+    // Make sure there is an empty object even if there are no APIs
+    newApplicationConfig.apis = {};
+  }
+
+  // Delete any existing files that were not overwritten
+  for (const filePath of existingFilePaths) {
+    await fs.remove(filePath);
+  }
+
+  await fs.ensureDir(`${appDirName}/${SUPERBLOCKS_HOME_FOLDER_NAME}`);
+
+  await fs.writeFile(
+    `${appDirName}/${RESOURCE_CONFIG_PATH}`,
+    JSON.stringify(sortByKey(newApplicationConfig), null, 2),
+  );
+
+  const createdFiles = await Promise.resolve<string[]>(
+    // Defensive check for when application settings are missing componentFiles
+    resource.componentFiles?.map((file: { filename: string; url: string }) =>
+      downloadFile(appDirName, file.filename, file.url),
+    ) ?? [],
+  );
+
+  // print out failed downloads synchronously here
+  createdFiles
+    .filter((createdFiles) => createdFiles.length)
+    .forEach((createdFile) => {
+      console.log(`Unable to download ${createdFile}`);
+    });
+
+  // do a post-migration cleanup if necessary
+  if (migrateFromSinglePage) {
+    await fs.remove(`${appDirName}/page.yaml`);
+    // delete app-level apis if they are not present in the new application config
+    if (!resource.apis || !resource.apis.length) {
+      await fs.remove(`${appDirName}/apis`);
+    }
+  }
+
+  return {
+    location: relativeLocation,
+    resourceType: "APPLICATION" as const,
+  };
+}
+
+async function writeCodeModeApplicationToDisk(
+  sdk: SuperblocksSdk,
+  resource: CodeModeApplicationWrapper,
+  appDirName: string,
+  featureFlags: FeatureFlags,
+): Promise<void> {
+  // Find the existing application config and existing file paths
+  const existingApplicationConfig =
+    await getSuperblocksApplicationConfigIfExists(appDirName);
+
+  const newApplicationConfig: SuperblocksApplicationV2Config = {
+    configType: "APPLICATION_V2",
+    id: resource.application.id,
+    metadata: getResourceConfigMetadata(
+      featureFlags,
+      existingApplicationConfig,
+    ),
+  };
+
+  await fs.ensureDir(`${appDirName}/${SUPERBLOCKS_HOME_FOLDER_NAME}`);
+
+  await fs.writeFile(
+    `${appDirName}/${RESOURCE_CONFIG_PATH}`,
+    JSON.stringify(sortByKey(newApplicationConfig), null, 2),
+  );
+
+  // This writes to DBFS
+  try {
+    await sdk.dbfsGetApplication({
+      applicationId: resource.application.id,
+      branch: DEFAULT_BRANCH,
+      localDirectoryPath: appDirName,
+    });
+  } catch (e) {
+    // This is most likely to happen if the application is not initialized
+    console.log(e);
+    throw e;
+  }
+}
+
+function getExistingFilePathsForApplicationApi(
+  superblocksApplicationConfig: SuperblocksApplicationConfig | undefined,
+  location: string,
+): Set<string> {
+  const paths = new Set<string>();
+  if (!superblocksApplicationConfig) {
+    return paths;
+  }
+  // Pages
+  if (superblocksApplicationConfig.pages) {
+    for (const page of Object.values(superblocksApplicationConfig.pages)) {
+      // Page YAML
+      const pageNameSlug = slugifyName(page.name);
+      const pagePath = `${location}/pages/${pageNameSlug}`;
+      paths.add(`${pagePath}/page.yaml`);
+
+      // Page APIs
+      if (page.pageApis) {
+        for (const api of Object.values(page.pageApis)) {
+          addExistingFilePathsForApi(api, `${pagePath}/apis`, paths, true);
+        }
+      } else if (page.apis) {
+        for (const apiName of Object.values(page.apis)) {
+          addExistingFilePathsForApi(
+            { name: apiName },
+            `${pagePath}/apis`,
+            paths,
+            true,
+          );
+        }
+      }
+    }
+  }
+  // APIs
+  if (superblocksApplicationConfig.appApis) {
+    // For file version >= 0.2.0, there are API files either the 'apis' folder or in an API-specific folder
+    for (const api of Object.values(superblocksApplicationConfig.appApis)) {
+      addExistingFilePathsForApi(api, `${location}/apis`, paths, true);
+    }
+  } else if (superblocksApplicationConfig.apis) {
+    // For file version < 0.2.0, there are only API file
+    for (const apiName of Object.values(superblocksApplicationConfig.apis)) {
+      addExistingFilePathsForApi(
+        { name: apiName },
+        `${location}/apis`,
+        paths,
+        true,
+      );
+    }
+  }
+  return paths;
+}
+
+function getExistingFilePathsForBackendApi(
+  superblocksBackendConfig: SuperblocksBackendConfig | undefined,
+  location: string,
+): Set<string> {
+  const paths = new Set<string>();
+  if (!superblocksBackendConfig) {
+    return paths;
+  }
+  // Pages
+  if (superblocksBackendConfig.sourceFiles) {
+    addExistingFilePathsForApi(
+      { name: "api", sourceFiles: superblocksBackendConfig.sourceFiles },
+      location,
+      paths,
+      false,
+    );
+  } else {
+    addExistingFilePathsForApi({ name: "api" }, location, paths, false);
+  }
+  return paths;
+}
+
+export function addExistingFilePathsForApi(
+  api: ApiInfo,
+  location: string,
+  paths: Set<string>,
+  useNestedFolder: boolean,
+) {
+  const apiNameSlug = slugifyName(api.name);
+  if (api.sourceFiles) {
+    // File version 0.2.0 and later
+    // API files are in an API-specific folder
+    const apiDirPath = useNestedFolder
+      ? `${location}/${apiNameSlug}`
+      : location;
+    paths.add(`${apiDirPath}/api.yaml`);
+    // And there are source files
+    for (const sourceFile of api.sourceFiles ?? []) {
+      paths.add(`${apiDirPath}/${sourceFile}`);
+    }
+  } else {
+    // Pre-file version 0.2.0
+    // API file is in the 'apis' folder with no separate source files
+    paths.add(`${location}/${apiNameSlug}.yaml`);
+  }
+  return paths;
+}
+
+function getResourceConfigMetadata(
+  featureFlags: FeatureFlags,
+  existingResourceConfig: SuperblocksResourceConfig | undefined,
+): SuperblocksResourceConfigMetadata | undefined {
+  if (!existingResourceConfig) {
+    // This is a new application, and we may need to add a metadata field to the application config
+    if (featureFlags.splitLargeApiStepsInNewEnabled()) {
+      return {
+        fileVersion: LATEST_FILE_VERSION,
+      };
+    }
+  } else if (existingResourceConfig.metadata) {
+    return existingResourceConfig.metadata;
+  }
+  return undefined;
+}
+
+export async function removeResourceFromDisk(
+  rootPath: string,
+  resourceRelativeLocation: string,
+) {
+  const resourceLocation = path.resolve(rootPath, resourceRelativeLocation);
+  await fs.remove(resourceLocation);
+}
+
+export async function getMode(
+  task: any,
+  mode: ModeFlag,
+): Promise<ExportViewMode> {
+  if (mode) {
+    return modeFlagToViewMode(mode);
+  }
+
+  const selectedMode = await task.prompt([
+    {
+      type: "Select",
+      name: "mode",
+      message: `Select which version of a resource you would like to fetch (${SELECT_PROMPT_HELP})`,
+      choices: Object.keys(modeFlagValuesMap).map((mode: string) => ({
+        name: mode,
+        message: modeFlagValuesMap[mode],
+      })),
+      initial: 0,
+      multiple: false,
+    },
+  ]);
+
+  return modeFlagToViewMode(selectedMode);
+}
+
+export function sortByKey(obj: unknown): unknown {
+  if (isArray(obj)) {
+    return obj.map((item) => sortByKey(item));
+  }
+
+  if (isObject(obj)) {
+    const sortedKeys = Object.keys(obj).sort();
+    const sortedObj: Record<string, any> = {};
+    for (const key of sortedKeys) {
+      sortedObj[key] = sortByKey(get(obj, key));
+    }
+
+    return sortedObj;
+  }
+
+  return obj;
+}
+
+export async function getLocalGitRepoState(
+  overrideLocalBranch?: string,
+): Promise<LocalGitRepoState> {
+  const git = simpleGit();
+
+  let status: StatusResult;
+  try {
+    // do not return untracked files which can be slow, we only care about the branch info
+    status = await git.status(["--untracked-files=no"]);
+  } catch {
+    return { status: "NO_GIT" };
+  }
+
+  let localBranchName: string;
+  if (overrideLocalBranch) {
+    const branches = await git.branch();
+    if (!branches.all.includes(overrideLocalBranch)) {
+      throw new Error(`There is no branch named ${overrideLocalBranch}`);
+    }
+    localBranchName = overrideLocalBranch;
+  } else {
+    if (status.detached || !status.current) {
+      return { status: "DETACHED" };
+    }
+    localBranchName = status.current;
+  }
+
+  const remoteName = (await git.getConfig(`branch.${localBranchName}.remote`))
+    ?.value;
+  if (!remoteName) {
+    return { status: "IN_A_BRANCH", localBranchName };
+  }
+  const remoteFetchUrl = (await git.getConfig(`remote.${remoteName}.url`))
+    ?.value;
+  if (!remoteFetchUrl) {
+    return { status: "IN_A_BRANCH", localBranchName };
+  }
+  const remotePushUrl = (await git.getConfig(`remote.${remoteName}.pushurl`))
+    ?.value;
+  let upstreamBranchName = (
+    await git.revparse(["--abbrev-ref", "--symbolic-full-name", "@{u}"])
+  ).split("\n", 1)[0];
+  if (upstreamBranchName.startsWith(`${remoteName}/`)) {
+    // `upstreamBranchName` is in the form `$remoteName/$branchName`, so we need to remove the `$remoteName/` part
+    upstreamBranchName = upstreamBranchName.substring(remoteName.length + 1);
+  }
+  return {
+    status: "IN_A_BRANCH",
+    localBranchName,
+    upstream: {
+      branchName: upstreamBranchName,
+      remoteName,
+      url: remoteFetchUrl,
+      pushUrl: remotePushUrl,
+    },
+  };
+}
+
+/**
+ * Returns the current git branch, or undefined if not in a git repo
+ */
+export async function getCurrentGitBranchIfGit(): Promise<string | null> {
+  const git: SimpleGit = simpleGit();
+  try {
+    // do not return untracked files which can be slow, we only care about the branch info
+    const status = await git.status(["--untracked-files=no"]);
+    const currentBranch = status.current;
+    return currentBranch;
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Returns the current git branch, or throws if not in a git repo
+ */
+export async function getCurrentGitBranch(): Promise<string> {
+  const currentBranch = await getCurrentGitBranchIfGit();
+  if (!currentBranch) {
+    throw new Error("No git repository found");
+  }
+  return currentBranch;
+}
+
+export async function getHeadCommit(branch: string): Promise<[string, string]> {
+  const git: SimpleGit = simpleGit();
+  let headCommitId;
+  let headCommitMessage;
+  const logResponse = await git.show(["--no-patch", "--format=%H%n%s", branch]);
+  const logLines = logResponse.split("\n");
+  if (logLines.length > 1) {
+    headCommitId = logLines[0];
+    headCommitMessage = logLines[1];
+  }
+  if (!headCommitId || !headCommitMessage) {
+    throw new Error(`Failed to get head commit for branch '${branch}'`);
+  }
+  return [headCommitId, headCommitMessage];
+}
+
+export function isCI(): boolean {
+  return process.env.CI === "true";
+}
+
+export async function isGitRepoDirty(): Promise<boolean> {
+  if (isCI()) {
+    // Skip dirtiness check in CI environments
+    return false;
+  }
+  const git: SimpleGit = simpleGit();
+  const status = await git.status();
+  return !status.isClean();
+}
+
+export function extractApiName(api: ApiWrapper): string {
+  return api.apiPb?.metadata?.name ?? api?.name ?? "Unknown";
+}
+
+export async function writeAppApi(
+  api: ApiWrapper,
+  directoryPath: string,
+  existingFilePaths: Set<string>,
+  apiPromises: Array<Promise<void>>,
+  apiRepresentation?: ApiRepresentation,
+): Promise<ApiInfo> {
+  const originalApiName = extractApiName(api);
+  const additionalStepFiles: AdditionalStepFiles[] = [];
+  await writeApiFiles(
+    api,
+    slugifyName(originalApiName),
+    `${directoryPath}/apis`,
+    true,
+    apiPromises,
+    additionalStepFiles,
+    apiRepresentation,
+    existingFilePaths,
+  );
+  return {
+    name: originalApiName,
+    sourceFiles: additionalStepFiles.map((file) => file.relativePath).sort(),
+  };
+}
+
+async function writeBackendApi(
+  api: ApiWrapper,
+  directoryPath: string,
+  apiPromises: Array<Promise<void>>,
+  apiRepresentation?: ApiRepresentation,
+  existingFilePaths?: Set<string>,
+): Promise<ApiInfo> {
+  const originalApiName = extractApiName(api);
+  const additionalStepFiles: AdditionalStepFiles[] = [];
+  await writeApiFiles(
+    api,
+    "api",
+    directoryPath,
+    false,
+    apiPromises,
+    additionalStepFiles,
+    apiRepresentation,
+    existingFilePaths,
+  );
+  return {
+    name: originalApiName,
+    sourceFiles: additionalStepFiles.map((file) => file.relativePath).sort(),
+  };
+}
+
+async function validateMultiPageApplication(
+  applicationConfig: SuperblocksApplicationConfig,
+  superblocksRootPath: string,
+  location: string,
+): Promise<string | undefined> {
+  // validate app level APIs
+  const apiNames = getApiNamesFromApplicationConfig(applicationConfig);
+  for (const apiName of apiNames) {
+    const apiPath = path.resolve(
+      superblocksRootPath,
+      location,
+      "apis",
+      `${slugifyName(apiName)}.yaml`,
+    );
+    const validateApiError = await validateYamlFile(apiPath);
+    if (validateApiError) {
+      return validateApiError;
+    }
+  }
+  // validate pages
+  for (const page of Object.values(applicationConfig.pages ?? {})) {
+    const pagePath = path.resolve(
+      superblocksRootPath,
+      location,
+      "pages",
+      slugifyName(page.name),
+      "page.yaml",
+    );
+    const validatePageError = await validateYamlFile(pagePath);
+    if (validatePageError) {
+      return validatePageError;
+    }
+    // validate page level APIs
+    const pageApiNames = getApiNamesFromPageConfig(page);
+    for (const apiName of pageApiNames) {
+      const apisPath = path.resolve(
+        superblocksRootPath,
+        location,
+        "pages",
+        slugifyName(page.name),
+        "apis",
+      );
+      // Try the API path not in a nested directory
+      const apiPath = path.resolve(apisPath, `${slugifyName(apiName)}.yaml`);
+      if (fs.pathExistsSync(apiPath)) {
+        const validateApiError = await validateYamlFile(apiPath);
+        if (validateApiError) {
+          return validateApiError;
+        }
+      } else {
+        // Try the API path in a nested directory
+        const nestedApiPath = path.resolve(
+          apisPath,
+          slugifyName(apiName),
+          "api.yaml",
+        );
+        if (fs.pathExistsSync(nestedApiPath)) {
+          const validateApiError = await validateYamlFile(nestedApiPath);
+          if (validateApiError) {
+            return validateApiError;
+          }
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+export async function validateLocalResource(
+  superblocksRootPath: string,
+  resource: VersionedResourceConfig,
+): Promise<string | undefined> {
+  switch (resource.resourceType) {
+    case "APPLICATION": {
+      // make sure application config exists
+      const applicationConfigPath = path.resolve(
+        superblocksRootPath,
+        resource.location,
+        RESOURCE_CONFIG_PATH,
+      );
+      if (!(await fs.pathExists(applicationConfigPath))) {
+        return `File ${relativeToCurrentDir(
+          applicationConfigPath,
+        )} not found. Superblocks CLI commands cannot function without it.`;
+      }
+      let applicationConfig:
+        | SuperblocksApplicationConfig
+        | SuperblocksApplicationV2Config
+        | undefined = undefined;
+      try {
+        applicationConfig = await getSuperblocksApplicationConfigJson(
+          path.join(superblocksRootPath, resource.location),
+        );
+      } catch {
+        // Noop
+      }
+      if (!applicationConfig) {
+        try {
+          applicationConfig = await getSuperblocksApplicationV2ConfigJson(
+            path.join(superblocksRootPath, resource.location),
+          );
+          if (!applicationConfig) {
+            throw new Error();
+          }
+        } catch {
+          return `File ${relativeToCurrentDir(
+            applicationConfigPath,
+          )} is not a valid JSON file. Please be sure it's valid JSON and rerun the command.`;
+        }
+      }
+      if (applicationConfig.configType === "APPLICATION_V2") {
+        // TODO(wylie): Implement validation for pushing V2 applications
+        break;
+      }
+      const applicationYamlPath = path.resolve(
+        superblocksRootPath,
+        resource.location,
+        "application.yaml",
+      );
+      // make sure application.yaml is a well-formed yaml file
+      try {
+        await readYamlFile(applicationYamlPath);
+      } catch {
+        return `File ${relativeToCurrentDir(
+          applicationYamlPath,
+        )} is not a valid YAML file. Please be sure it's valid YAML and rerun the command.`;
+      }
+      const validationError = validateMultiPageApplication(
+        applicationConfig,
+        superblocksRootPath,
+        resource.location,
+      );
+      if (validationError) {
+        return validationError;
+      }
+      break;
+    }
+    case "BACKEND": {
+      // make sure the backend config exists
+      const backendConfigPath = path.resolve(
+        superblocksRootPath,
+        resource.location,
+        RESOURCE_CONFIG_PATH,
+      );
+      if (!(await fs.pathExists(backendConfigPath))) {
+        return `File ${relativeToCurrentDir(
+          backendConfigPath,
+        )} not found. Superblocks CLI commands cannot function without it.`;
+      }
+      // make sure it's a well-formed backend config
+      try {
+        await fs.readJSON(backendConfigPath);
+      } catch {
+        return `File ${relativeToCurrentDir(
+          backendConfigPath,
+        )} is not a valid JSON file. Please be sure it's valid JSON and rerun the command.`;
+      }
+      // make sure that api.yaml exists
+      const apiYamlPath = path.resolve(
+        superblocksRootPath,
+        resource.location,
+        "api.yaml",
+      );
+      const validateYamlFileError = await validateYamlFile(apiYamlPath);
+      if (validateYamlFileError) {
+        return validateYamlFileError;
+      }
+      break;
+    }
+  }
+  return undefined;
+}
+
+export async function deleteResourcesAndUpdateRootConfig(
+  removedResourceIds: string[],
+  existingSuperblocksRootConfig: SuperblocksMonorepoConfig,
+  superblocksRootPath: string,
+  superblocksRootConfigPath: string,
+): Promise<void> {
+  for (const resourceId of removedResourceIds) {
+    const resource = existingSuperblocksRootConfig?.resources[resourceId];
+    await removeResourceFromDisk(superblocksRootPath, resource.location);
+  }
+  for (const removedResourceId of removedResourceIds) {
+    delete existingSuperblocksRootConfig.resources[removedResourceId];
+  }
+  // update superblocks.json file with removed resources
+  await fs.writeFile(
+    superblocksRootConfigPath,
+    JSON.stringify(sortByKey(existingSuperblocksRootConfig), null, 2),
+  );
+}
+
+async function validateYamlFile(yamlPath: string): Promise<string | undefined> {
+  // make sure a yaml file is well-formed
+  try {
+    await readYamlFile(yamlPath);
+  } catch {
+    return `File ${relativeToCurrentDir(
+      yamlPath,
+    )} is not a valid YAML file. Please be sure it's valid YAML and rerun the command.`;
+  }
+}
+
+function relativeToCurrentDir(applicationConfigPath: string) {
+  return `./${path.relative(process.cwd(), applicationConfigPath)}`;
+}