@superblocksteam/cli 1.9.3 → 1.12.0

package/dist/common/version-control.mjs

@@ -0,0 +1,1064 @@
+import * as https from "https";
+import path from "node:path";
+import { dirname } from "path";
+import { DEFAULT_LINES_FOR_LARGE_STEPS, } from "@superblocksteam/sdk";
+import { RESOURCE_CONFIG_PATH, SUPERBLOCKS_HOME_FOLDER_NAME, getSuperblocksApplicationConfigIfExists, getSuperblocksApplicationConfigJson, getSuperblocksBackendConfigIfExists, } from "@superblocksteam/util";
+import { bold } from "colorette";
+import fs from "fs-extra";
+import { isEmpty, isArray, isObject, get, cloneDeep } from "lodash-es";
+import * as semver from "semver";
+import { simpleGit } from "simple-git";
+import slugify from "slugify";
+import { parse, stringify as ymlstringify } from "yaml";
+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";
+const LANGUAGE_STEP_EXTENSIONS = {
+    javascript: "js",
+    python: "py",
+};
+export const modeFlagValuesMap = {
+    [LATEST_EDITS_MODE]: "Latest edits",
+    [MOST_RECENT_COMMIT_MODE]: "Most recent commit",
+    [DEPLOYED_MODE]: "Deployed",
+};
+export var FileStructureType;
+(function (FileStructureType) {
+    FileStructureType["SINGLE_PAGE"] = "single-page";
+    FileStructureType["MULTI_PAGE"] = "multi-page";
+})(FileStructureType || (FileStructureType = {}));
+export function modeFlagToViewMode(modeFlag) {
+    switch (modeFlag) {
+        case LATEST_EDITS_MODE:
+            return "export-live";
+        case MOST_RECENT_COMMIT_MODE:
+            return "export-latest";
+        case DEPLOYED_MODE:
+            return "export-deployed";
+        default:
+            throw new Error(`Unsupported mode flag: ${modeFlag}`);
+    }
+}
+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) => {
+    if (isEmpty(value)) {
+        return `Please select at least one item ${bold("by pressing space")}`;
+    }
+    return true;
+};
+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, resourceConfig) {
+    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) {
+    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) {
+    return slugify(originalName, {
+        replacement: "_",
+        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(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("");
+}
+export async function readAppApiYamlFile(parentDirectory, apiName) {
+    // The API is either stored in its entirety in a single YAML file, or
+    // or in a subdirectory containing the YAML file and zero or more language-specific files.
+    const apiNameSlug = slugifyName(apiName ?? "api");
+    const singularApiYamlPath = `${parentDirectory}/${apiNameSlug}.yaml`;
+    const apiDirPath = `${parentDirectory}/${apiNameSlug}`;
+    const nestedApiYamlPath = `${apiDirPath}/api.yaml`;
+    // Read the YAML file
+    let yamlPath;
+    let yamlParentPath;
+    if (await fs.pathExists(singularApiYamlPath)) {
+        // The API YAML file is in the parent directory
+        yamlPath = singularApiYamlPath;
+        yamlParentPath = parentDirectory;
+    }
+    else if (await fs.pathExists(nestedApiYamlPath)) {
+        // The API YAML file is nested in an API-specific directory
+        yamlPath = nestedApiYamlPath;
+        yamlParentPath = apiDirPath;
+    }
+    else {
+        throw new Error(`API ${apiName ?? ""} not found at ${parentDirectory}`);
+    }
+    // That is nested in an API-specific directory
+    const apiDefn = (await readYamlFile(yamlPath));
+    // The API YAML file may or may not have language-specific content in separate files.
+    // Replace any file references with the actual content
+    await resolveLanguageSpecificStepContentFromBlocks(yamlParentPath, apiDefn.blocks ?? []);
+    return apiDefn;
+}
+async function resolveLanguageSpecificStepContentFromBlocks(parentPath, blocks) {
+    for (const block of blocks) {
+        // Handle language-specific step content
+        if (block.step) {
+            const step = block.step;
+            await resolveLanguageSpecificStepContentFromStep(parentPath, step);
+        }
+        // Handle conditional blocks
+        if (block.conditional) {
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.conditional.if?.blocks ?? []);
+            for (const elseIfBlock of block.conditional.elseIf) {
+                await resolveLanguageSpecificStepContentFromBlocks(parentPath, elseIfBlock.blocks);
+            }
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.conditional.else?.blocks ?? []);
+        }
+        // Handle loop blocks
+        await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.loop?.blocks ?? []);
+        // Handle try-catch blocks
+        if (block.tryCatch) {
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.tryCatch.try?.blocks ?? []);
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.tryCatch.catch?.blocks ?? []);
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.tryCatch.finally?.blocks ?? []);
+        }
+        // Handle parallel blocks
+        if (block.parallel) {
+            for (const path of Object.values(block.parallel?.static?.paths ?? {})) {
+                await resolveLanguageSpecificStepContentFromBlocks(parentPath, path.blocks);
+            }
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.parallel?.dynamic?.blocks ?? []);
+        }
+        // Handle stream blocks
+        if (block.stream) {
+            await resolveLanguageSpecificStepContentFromBlocks(parentPath, block.stream.process?.blocks ?? []);
+            await resolveLanguageSpecificStepContentFromStep(parentPath, block.stream.trigger?.step ?? {});
+        }
+    }
+}
+async function resolveLanguageSpecificStepContentFromStep(parentPath, step) {
+    // Handle language-specific step content
+    if (!step?.integration || !LANGUAGE_STEP_EXTENSIONS[step.integration]) {
+        return;
+    }
+    const languageContent = step[step.integration];
+    if (languageContent.body &&
+        typeof languageContent.body === "object" &&
+        "path" in languageContent.body) {
+        const languageFilePath = `${parentPath}/${languageContent.body.path}`;
+        if (await fs.pathExists(languageFilePath)) {
+            // Read the file content
+            const stepBodyContent = await fs.readFile(languageFilePath, "utf8");
+            if (stepBodyContent && languageContent) {
+                languageContent.body = stepBodyContent;
+            }
+        }
+    }
+}
+async function readYamlFile(path) {
+    return parse(await fs.readFile(path, "utf8"));
+}
+function getFileStructureTypeFromResourceConfig(superblocksConfig) {
+    if (superblocksConfig.pages) {
+        return FileStructureType.MULTI_PAGE;
+    }
+    return FileStructureType.SINGLE_PAGE;
+}
+export async function getFileStructureType(rootPath, existingRelativeLocation) {
+    const superblocksConfig = await getSuperblocksApplicationConfigJson(`${rootPath}/${existingRelativeLocation}`);
+    return getFileStructureTypeFromResourceConfig(superblocksConfig);
+}
+// 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, existingRelativeLocation) {
+    const application = await readYamlFile(`${rootPath}/${existingRelativeLocation}/application.yaml`);
+    const page = await readYamlFile(`${rootPath}/${existingRelativeLocation}/page.yaml`);
+    const apisDirName = `${rootPath}/${existingRelativeLocation}/apis`;
+    const apis = [];
+    if (await fs.pathExists(apisDirName)) {
+        const apiFiles = await fs.readdir(apisDirName);
+        for (const apiFile of apiFiles) {
+            const 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, existingRelativeLocation) {
+    const superblocksApplicationConfig = await getSuperblocksApplicationConfigJson(`${rootPath}/${existingRelativeLocation}`);
+    const application = await readYamlFile(`${rootPath}/${existingRelativeLocation}/application.yaml`);
+    const pagesDirName = `${rootPath}/${existingRelativeLocation}/pages`;
+    const pages = [];
+    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 = [];
+            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 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 = [];
+    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 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) {
+    return applicationConfig.appApis
+        ? Object.values(applicationConfig.appApis).map((api) => api.name)
+        : Object.values(applicationConfig.apis ?? {});
+}
+function getApiNamesFromPageConfig(pageConfig) {
+    return pageConfig.pageApis
+        ? Object.values(pageConfig.pageApis).map((api) => api.name)
+        : Object.values(pageConfig.apis ?? {});
+}
+export async function readApiFromDisk(rootPath, existingRelativeLocation) {
+    const path = `${rootPath}/${existingRelativeLocation}`;
+    const 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, resourceId, resource, rootPath, featureFlags, existingRelativeLocation, preferredApiRepresentation) {
+    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 = [];
+            const apisDirName = `${appDirName}/apis`;
+            await fs.ensureDir(apisDirName);
+            const existingApplicationConfig = await getSuperblocksApplicationConfigIfExists(appDirName);
+            const existingFilePaths = getExistingFilePathsForApplicationApi(existingApplicationConfig, appDirName);
+            const newApplicationConfig = {
+                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) {
+                    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(
+            // Defensive check for when application settings are missing componentFiles
+            resource.componentFiles?.map((file) => 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 = {
+                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 writeMultiPageApplicationToDisk(resource, rootPath, featureFlags, existingRelativeLocation, migrateFromSinglePage, preferredApiRepresentation) {
+    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);
+    // Find the existing application config and existing file paths
+    const existingApplicationConfig = await getSuperblocksApplicationConfigIfExists(appDirName);
+    const existingFilePaths = getExistingFilePathsForApplicationApi(existingApplicationConfig, appDirName);
+    const newApplicationConfig = {
+        configType: "APPLICATION",
+        id: resource.application.id,
+        metadata: getResourceConfigMetadata(featureFlags, existingApplicationConfig),
+    };
+    const apiRepresentation = preferredApiRepresentation ??
+        getApiRepresentation(featureFlags, newApplicationConfig);
+    newApplicationConfig.pages = {};
+    const apiPromises = [];
+    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) {
+            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 = {};
+    if (resource.apis && resource.apis.length) {
+        for (const api of resource.apis) {
+            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(
+    // Defensive check for when application settings are missing componentFiles
+    resource.componentFiles?.map((file) => 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",
+    };
+}
+function getExistingFilePathsForApplicationApi(superblocksApplicationConfig, location) {
+    const paths = new Set();
+    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, location) {
+    const paths = new Set();
+    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, location, paths, useNestedFolder) {
+    const apiNameSlug = slugifyName(api.name);
+    if (api.sourceFiles?.length) {
+        // API files are in an API-specific folder
+        const apiDirPath = useNestedFolder
+            ? `${location}/${apiNameSlug}`
+            : location;
+        paths.add(`${apiDirPath}/${apiNameSlug}.yaml`);
+        // And there are source files
+        for (const sourceFile of api.sourceFiles ?? []) {
+            paths.add(`${apiDirPath}/${sourceFile}`);
+        }
+    }
+    else {
+        // API file is in the 'apis' folder with no separate source files
+        paths.add(`${location}/${apiNameSlug}.yaml`);
+    }
+    return paths;
+}
+function getResourceConfigMetadata(featureFlags, existingResourceConfig) {
+    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, resourceRelativeLocation) {
+    const resourceLocation = path.resolve(rootPath, resourceRelativeLocation);
+    await fs.remove(resourceLocation);
+}
+export async function getMode(task, mode) {
+    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) => ({
+                name: mode,
+                message: modeFlagValuesMap[mode],
+            })),
+            initial: 0,
+            multiple: false,
+        },
+    ]);
+    return modeFlagToViewMode(selectedMode);
+}
+export function sortByKey(obj) {
+    if (isArray(obj)) {
+        return obj.map((item) => sortByKey(item));
+    }
+    if (isObject(obj)) {
+        const sortedKeys = Object.keys(obj).sort();
+        const sortedObj = {};
+        for (const key of sortedKeys) {
+            sortedObj[key] = sortByKey(get(obj, key));
+        }
+        return sortedObj;
+    }
+    return obj;
+}
+export async function getLocalGitRepoState(overrideLocalBranch) {
+    const git = simpleGit();
+    let status;
+    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;
+    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() {
+    const git = 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() {
+    const currentBranch = await getCurrentGitBranchIfGit();
+    if (!currentBranch) {
+        throw new Error("No git repository found");
+    }
+    return currentBranch;
+}
+export async function getHeadCommit(branch) {
+    const git = 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() {
+    return process.env.CI === "true";
+}
+export async function isGitRepoDirty() {
+    if (isCI()) {
+        // Skip dirtiness check in CI environments
+        return false;
+    }
+    const git = simpleGit();
+    const status = await git.status();
+    return !status.isClean();
+}
+export function extractApiName(api) {
+    return api.apiPb?.metadata?.name ?? api?.name ?? "Unknown";
+}
+export async function writeAppApi(api, directoryPath, existingFilePaths, apiPromises, apiRepresentation) {
+    const originalApiName = extractApiName(api);
+    const 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, directoryPath, apiPromises, apiRepresentation, existingFilePaths) {
+    const originalApiName = extractApiName(api);
+    const additionalStepFiles = [];
+    await writeApiFiles(api, "api", directoryPath, false, apiPromises, additionalStepFiles, apiRepresentation, existingFilePaths);
+    return {
+        name: originalApiName,
+        sourceFiles: additionalStepFiles.map((file) => file.relativePath).sort(),
+    };
+}
+async function writeApiFiles(api, apiNameSlug, directoryPath, nestedApiFiles, apiPromises, additionalStepFiles, apiRepresentation, existingFilePaths) {
+    let pathForApiFile = directoryPath;
+    let yamlFileName = `${apiNameSlug}.yaml`;
+    // Determine whether to extract into separate files  the source code from the steps
+    const updatedApi = extractAdditionalStepFiles(api.apiPb, additionalStepFiles, apiRepresentation);
+    if (apiRepresentation?.extractLargeSourceFiles) {
+        if (nestedApiFiles) {
+            // This API has at least one large step code file, so we need a nested directory
+            pathForApiFile = `${pathForApiFile}/${apiNameSlug}`;
+            yamlFileName = "api.yaml";
+        }
+        // Make sure the directory exists
+        await fs.ensureDir(pathForApiFile);
+        // Write any additional step source code files to the disk
+        for (const stepFile of additionalStepFiles) {
+            const sourceFilePath = `${pathForApiFile}/${stepFile.relativePath}`;
+            const handleApi = async () => {
+                await fs.outputFile(sourceFilePath, stepFile.contents);
+            };
+            apiPromises.push(handleApi());
+            // Mark the existing source file as being reused
+            existingFilePaths?.delete(sourceFilePath);
+        }
+    }
+    else {
+        // No additional step files to write, so mark the API directory as existing so that it will be removed later.
+        // Do this even if the current representation does not extract large source files, in case they were previously
+        existingFilePaths?.add(`${directoryPath}/${apiNameSlug}`);
+    }
+    // Convert the updated API to YAML and write it to disk
+    const apiContent = ymlstringify(updatedApi, {
+        sortMapEntries: true,
+        blockQuote: "literal",
+    });
+    const yamlFilePath = `${pathForApiFile}/${yamlFileName}`;
+    const handleApi = async () => {
+        await fs.outputFile(yamlFilePath, apiContent);
+    };
+    apiPromises.push(handleApi());
+    // Mark the existing source file as being reused
+    existingFilePaths?.delete(yamlFilePath);
+}
+function extractAdditionalStepFiles(api, additionalStepFiles, apiRepresentation) {
+    if (!api.blocks || !apiRepresentation?.extractLargeSourceFiles) {
+        return api;
+    }
+    const apiClone = cloneDeep(api);
+    const minLinesForExtraction = apiRepresentation?.minLinesForExtraction ?? DEFAULT_LINES_FOR_LARGE_STEPS;
+    const existingFilePaths = new Set();
+    extractAdditionalStepFilesFromBlocks(apiClone.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+    return apiClone;
+}
+function extractAdditionalStepFilesFromBlocks(blocks, additionalStepFiles, existingFilePaths, minLinesForExtraction) {
+    for (const block of blocks) {
+        // Handle language step files
+        if (block.step) {
+            extractAdditionalStepFilesFromStep(block.step, block.name, additionalStepFiles, existingFilePaths, minLinesForExtraction);
+        }
+        // Handle loops
+        extractAdditionalStepFilesFromBlocks(block.loop?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+        // Handle try/catch
+        if (block.tryCatch) {
+            extractAdditionalStepFilesFromBlocks(block.tryCatch.try?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+            extractAdditionalStepFilesFromBlocks(block.tryCatch.catch?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+            extractAdditionalStepFilesFromBlocks(block.tryCatch.finally?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+        }
+        // Handle conditional
+        if (block.conditional) {
+            extractAdditionalStepFilesFromBlocks(block.conditional.if?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+            for (const elseIfBlock of block.conditional.elseIf ?? []) {
+                extractAdditionalStepFilesFromBlocks(elseIfBlock.blocks, additionalStepFiles, existingFilePaths, minLinesForExtraction);
+            }
+            extractAdditionalStepFilesFromBlocks(block.conditional.else?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+        }
+        // Handle Parallel API
+        if (block.parallel) {
+            for (const path of Object.values(block.parallel?.static?.paths ?? {})) {
+                extractAdditionalStepFilesFromBlocks(path.blocks, additionalStepFiles, existingFilePaths, minLinesForExtraction);
+            }
+            extractAdditionalStepFilesFromBlocks(block.parallel?.dynamic?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+        }
+        // Handle stream
+        if (block.stream) {
+            const trigger = block.stream.trigger;
+            if (trigger && trigger.step) {
+                extractAdditionalStepFilesFromStep(trigger.step, trigger.name, additionalStepFiles, existingFilePaths, minLinesForExtraction);
+            }
+            extractAdditionalStepFilesFromBlocks(block.stream.process?.blocks ?? [], additionalStepFiles, existingFilePaths, minLinesForExtraction);
+        }
+    }
+}
+function extractAdditionalStepFilesFromStep(step, name, additionalStepFiles, existingFilePaths, minLinesForExtraction) {
+    // Handle language step files
+    if (step && "integration" in step) {
+        const integration = step.integration;
+        const extension = LANGUAGE_STEP_EXTENSIONS[integration];
+        if (extension) {
+            const languageContent = step[integration];
+            if (languageContent) {
+                const blockBody = languageContent.body;
+                if (blockBody && typeof blockBody === "string") {
+                    const lines = blockBody?.split("\n");
+                    const linesNum = lines?.length;
+                    if (linesNum && linesNum > minLinesForExtraction) {
+                        // Record the separate file is needed, with the language contents
+                        const relativePath = findUnusedFilePath(slugifyName(name), extension, existingFilePaths);
+                        additionalStepFiles.push({
+                            relativePath: relativePath,
+                            contents: blockBody,
+                            language: integration,
+                        });
+                        // Replace the body with a reference to the separate file
+                        languageContent.body = {
+                            path: `./${relativePath}`,
+                        };
+                    }
+                }
+            }
+        }
+    }
+}
+function findUnusedFilePath(filename, extension, existingFilePaths) {
+    let proposedFilename = `${filename}.${extension}`;
+    let i = 1;
+    while (existingFilePaths.has(proposedFilename)) {
+        proposedFilename = `${filename}_${i}.${extension}`;
+        i++;
+    }
+    existingFilePaths.add(proposedFilename);
+    return proposedFilename;
+}
+async function validateMultiPageApplication(applicationConfig, superblocksRootPath, location) {
+    // 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, resource) {
+    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 = undefined;
+            try {
+                // make sure it's a well-formed application config
+                applicationConfig = await fs.readJSON(applicationConfigPath);
+                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.`;
+            }
+            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, existingSuperblocksRootConfig, superblocksRootPath, superblocksRootConfigPath) {
+    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) {
+    // 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) {
+    return `./${path.relative(process.cwd(), applicationConfigPath)}`;
+}