@superblocksteam/util 1.14.2 → 2.0.3-next.50

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC,UAAU,sBAAsB,CAAC,CAAC,SAAS,QAAQ;IACjD;;;;OAIG;IACH,WAAW,EAAE,CAAC,SAAS,SAAS,GAC5B,MAAM,GAAG,SAAS,GAAG,QAAQ,GAC7B,MAAM,GAAG,SAAS,CAAC;IAEvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,QAAQ;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,CAAC;IAEZ;;;QAGI;IACJ,sBAAsB,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAEnD;;;QAGI;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;QAGI;IACJ,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,QAAQ,GAChB,eAAe,CAAC,QAAQ,CAAC,GACzB,eAAe,CAAC,QAAQ,CAAC,GACzB,eAAe,CAAC,SAAS,CAAC,GAC1B,eAAe,CAAC,KAAK,CAAC,CAAC;AAE3B,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,IAAI,CAAC;IAET;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB,UAAU,EAAE,KAAK,CAIb,eAAe,CAAC,QAAQ,CAAC,GACzB,eAAe,CAAC,QAAQ,CAAC,GACzB,eAAe,CAAC,SAAS,CAAC,GAC1B,eAAe,CAAC,KAAK,CAAC,CACzB,CAAC;IAEF;;;;;OAKG;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IAEH,cAAc,CAAC,EAAE;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH"}

package/dist/types.js

@@ -1,2 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/unreachable.d.ts

@@ -1 +1,2 @@
-export declare function unreachable(value: never): never;
+export declare function unreachable(value: never, errMsg?: string): never;
+//# sourceMappingURL=unreachable.d.ts.map

package/dist/unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../src/unreachable.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAIhE"}

package/dist/unreachable.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unreachable = unreachable;
-function unreachable(value) {
-    throw new TypeError("Encountered impossible value: " + JSON.stringify(value));
+function unreachable(value, errMsg) {
+    throw new TypeError(errMsg ?? "Encountered impossible value: " + JSON.stringify(value));
 }
+//# sourceMappingURL=unreachable.js.map

package/dist/unreachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.js","sourceRoot":"","sources":["../src/unreachable.ts"],"names":[],"mappings":";;AAAA,kCAIC;AAJD,SAAgB,WAAW,CAAC,KAAY,EAAE,MAAe;IACvD,MAAM,IAAI,SAAS,CACjB,MAAM,IAAI,gCAAgC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CACnE,CAAC;AACJ,CAAC"}

package/dist/validation.d.ts

@@ -2,3 +2,4 @@ export declare function validateCustomComponents(data: any): {
     valid: boolean;
     message?: string;
 };
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AA4IA,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,GAAG,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAWA"}

package/dist/validation.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateCustomComponents = validateCustomComponents;
 const ajv_1 = __importDefault(require("ajv"));
 const better_ajv_errors_1 = __importDefault(require("better-ajv-errors"));
-const identifiers_1 = require("./identifiers");
+const identifiers_js_1 = require("./identifiers.js");
 const ajv = new ajv_1.default();
 ajv.addKeyword({
     keyword: "stringFormat",
@@ -17,7 +17,7 @@ ajv.addKeyword({
             validateFunc = (data) => {
                 if (typeof data != "string")
                     return false;
-                if (!(0, identifiers_1.isValidIdentifier)(data)) {
+                if (!(0, identifiers_js_1.isValidIdentifier)(data)) {
                     validateFunc.errors = [
                         {
                             keyword: "format",
@@ -26,7 +26,7 @@ ajv.addKeyword({
                     ];
                     return false;
                 }
-                if ((0, identifiers_1.isReservedPropertyName)(data)) {
+                if ((0, identifiers_js_1.isReservedPropertyName)(data)) {
                     validateFunc.errors = [
                         {
                             keyword: "format",
@@ -149,3 +149,4 @@ function validateCustomComponents(data) {
     }
     return { valid: true };
 }
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/eslint.config.js

@@ -21,7 +21,7 @@ const config = [
   },
   js.configs.recommended,
   ...tseslint.configs.recommended,
-  eslintPluginPrettierRecommended,
+  { files: ["./*", "src/**"], ...eslintPluginPrettierRecommended },
   {
     plugins: {
       "@typescript-eslint": tseslint.plugin,
@@ -39,6 +39,8 @@ const config = [
       "@typescript-eslint/no-explicit-any": "off",
       "@typescript-eslint/no-unused-vars": "error",
       "@typescript-eslint/no-var-requires": "off",
+      "@typescript-eslint/no-import-type-side-effects": "error",
+      "@typescript-eslint/consistent-type-imports": "error",
       "unicorn/no-nested-ternary": "off",
       "import/order": [
         "error",
@@ -57,6 +59,14 @@ const config = [
         },
       ],
       "import/no-cycle": "error",
+      "import/extensions": [
+        "error",
+        "ignorePackages",
+        {
+          ts: "never",
+          tsx: "never",
+        },
+      ],
       "no-template-curly-in-string": "off",
       "no-useless-escape": "off",
       "no-void": ["error", { allowAsStatement: true }],

package/package.json

@@ -1,39 +1,46 @@
 {
   "name": "@superblocksteam/util",
-  "version": "1.14.2",
-  "main": "dist/index.js",
+  "description": "",
+  "version": "2.0.3-next.50",
   "homepage": "https://www.superblocks.com",
   "license": "Superblocks Community Software License",
-  "description": "",
+  "main": "dist/index.js",
   "dependencies": {
     "ajv": "^8.12.0",
-    "better-ajv-errors": "^1.2.0",
+    "better-ajv-errors": "1.2.0",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
+    "lodash-es": "^4.17.21",
     "mime-types": "^2.1.35",
-    "typescript": "^5.1.3"
+    "slugify": "^1.6.6",
+    "typescript": "^5.1.3",
+    "yaml": "^2.4.2"
   },
   "devDependencies": {
+    "@eslint/js": "^9.16.0",
     "@types/fs-extra": "^11.0.1",
     "@types/lodash": "^4.17.7",
+    "@types/lodash-es": "^4.17.12",
     "@types/mime-types": "^2.1.1",
     "@types/node": "^20.11.18",
     "@typescript-eslint/eslint-plugin": "^8.25.0",
     "@typescript-eslint/parser": "^8.25.0",
     "eslint": "^9.21.0",
+    "eslint-plugin-import": "2.31.0",
+    "eslint-plugin-mocha": "^10.5.0",
     "eslint-plugin-prettier": "^5.2.5",
     "eslint-plugin-unicorn": "^47.0.0",
     "prettier": "^3.5.2",
-    "tslib": "^2.5.0"
+    "tslib": "^2.5.0",
+    "typescript-eslint": "^8.18.0"
   },
   "scripts": {
-    "dev": "tsc --watch",
     "build": "tsc --build",
-    "clean": "npm run clean:build && rm -rf node_modules",
-    "clean:build": "tsc --build --clean && rm -rf dist tsconfig.tsbuildinfo",
+    "check": "pnpm run lint && pnpm run typecheck",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "dev": "tsc --build --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "typecheck": "tsc --noEmit",
-    "check": "pnpm run lint && pnpm run typecheck"
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/api-files/api.mts

@@ -0,0 +1,504 @@
+import fs from "fs-extra";
+import { cloneDeep } from "lodash-es";
+import slugify from "slugify";
+import { parse, stringify as ymlstringify } from "yaml";
+import {
+  DEFAULT_LINES_FOR_LARGE_STEPS,
+  LANGUAGE_STEP_EXTENSIONS,
+} from "./constants.js";
+import type {
+  AdditionalStepFiles,
+  Api,
+  ApiRepresentation,
+  ApiWrapper,
+  Block,
+  LanguageContent,
+  Step,
+} from "./types.js";
+
+function slugifyName(originalName: any): string {
+  return (slugify as any)(originalName, {
+    replacement: "_",
+    lower: true,
+  });
+}
+
+function findUnusedFilePath(
+  filename: string,
+  extension: string,
+  existingFilePaths: Set<string>,
+): string {
+  let proposedFilename = `${filename}.${extension}`;
+  let i = 1;
+  while (existingFilePaths.has(proposedFilename)) {
+    proposedFilename = `${filename}_${i}.${extension}`;
+    i++;
+  }
+  existingFilePaths.add(proposedFilename);
+  return proposedFilename;
+}
+
+function extractAdditionalStepFiles(
+  api: Api,
+  additionalStepFiles: AdditionalStepFiles[],
+  stepPathMap: Record<string, string>,
+  currentStepNames: string[],
+  apiRepresentation?: ApiRepresentation,
+): Api {
+  if (!api.blocks || !apiRepresentation?.extractLargeSourceFiles) {
+    return api;
+  }
+  // TODO: lodash
+  const apiClone = cloneDeep(api);
+  const minLinesForExtraction =
+    apiRepresentation?.minLinesForExtraction ?? DEFAULT_LINES_FOR_LARGE_STEPS;
+  const existingFilePaths = new Set<string>();
+  extractAdditionalStepFilesFromBlocks(
+    apiClone.blocks ?? [],
+    additionalStepFiles,
+    existingFilePaths,
+    minLinesForExtraction,
+    stepPathMap,
+    currentStepNames,
+  );
+  return apiClone;
+}
+
+function extractAdditionalStepFilesFromStep(
+  step: Step,
+  name: string,
+  additionalStepFiles: AdditionalStepFiles[],
+  existingFilePaths: Set<string>,
+  minLinesForExtraction: number,
+  stepPathMap: Record<string, string>,
+  currentStepNames: string[],
+) {
+  // Handle language step files
+  if (step && "integration" in step) {
+    const integration = step.integration as keyof Step;
+    const extension =
+      LANGUAGE_STEP_EXTENSIONS[
+        integration as keyof typeof LANGUAGE_STEP_EXTENSIONS
+      ];
+    if (extension) {
+      const languageContent = step[integration] as LanguageContent;
+      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
+            let relativePath;
+            if (stepPathMap?.[name]) {
+              relativePath = stepPathMap[name].startsWith("./")
+                ? stepPathMap[name].split("./")?.[1]
+                : stepPathMap[name];
+            } else {
+              relativePath = findUnusedFilePath(
+                slugifyName(name),
+                extension,
+                existingFilePaths,
+              );
+              stepPathMap[name] = `./${relativePath}`;
+            }
+            additionalStepFiles.push({
+              relativePath: relativePath,
+              contents: blockBody,
+              language: integration,
+            });
+            currentStepNames.push(name);
+            // Replace the body with a reference to the separate file
+            languageContent.body = {
+              path: `./${relativePath}`,
+            };
+          }
+        }
+      }
+    }
+  }
+}
+
+function extractAdditionalStepFilesFromBlocks(
+  blocks: Block[],
+  additionalStepFiles: AdditionalStepFiles[],
+  existingFilePaths: Set<string>,
+  minLinesForExtraction: number,
+  stepPathMap: Record<string, string>,
+  currentStepNames: string[],
+) {
+  for (const block of blocks) {
+    // Handle language step files
+    if (block.step) {
+      extractAdditionalStepFilesFromStep(
+        block.step,
+        block.name,
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+    }
+
+    // Handle loops
+    extractAdditionalStepFilesFromBlocks(
+      block.loop?.blocks ?? [],
+      additionalStepFiles,
+      existingFilePaths,
+      minLinesForExtraction,
+      stepPathMap,
+      currentStepNames,
+    );
+    // Handle try/catch
+    if (block.tryCatch) {
+      extractAdditionalStepFilesFromBlocks(
+        block.tryCatch.try?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+      extractAdditionalStepFilesFromBlocks(
+        block.tryCatch.catch?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+      extractAdditionalStepFilesFromBlocks(
+        block.tryCatch.finally?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+    }
+    // Handle conditional
+    if (block.conditional) {
+      extractAdditionalStepFilesFromBlocks(
+        block.conditional.if?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+      for (const elseIfBlock of block.conditional.elseIf ?? []) {
+        extractAdditionalStepFilesFromBlocks(
+          elseIfBlock.blocks,
+          additionalStepFiles,
+          existingFilePaths,
+          minLinesForExtraction,
+          stepPathMap,
+          currentStepNames,
+        );
+      }
+      extractAdditionalStepFilesFromBlocks(
+        block.conditional.else?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+    }
+    // Handle Parallel API
+    if (block.parallel) {
+      for (const path of Object.values(block.parallel?.static?.paths ?? {})) {
+        extractAdditionalStepFilesFromBlocks(
+          path.blocks,
+          additionalStepFiles,
+          existingFilePaths,
+          minLinesForExtraction,
+          stepPathMap,
+          currentStepNames,
+        );
+      }
+      extractAdditionalStepFilesFromBlocks(
+        block.parallel?.dynamic?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+    }
+    // Handle stream
+    if (block.stream) {
+      const trigger = block.stream.trigger;
+      if (trigger && trigger.step) {
+        extractAdditionalStepFilesFromStep(
+          trigger.step,
+          trigger.name,
+          additionalStepFiles,
+          existingFilePaths,
+          minLinesForExtraction,
+          stepPathMap,
+          currentStepNames,
+        );
+      }
+      extractAdditionalStepFilesFromBlocks(
+        block.stream.process?.blocks ?? [],
+        additionalStepFiles,
+        existingFilePaths,
+        minLinesForExtraction,
+        stepPathMap,
+        currentStepNames,
+      );
+    }
+  }
+}
+
+async function readYamlFile(path: string): Promise<any> {
+  return parse(await fs.readFile(path, "utf8"));
+}
+
+async function resolveLanguageSpecificStepContentFromBlocks(
+  parentPath: string,
+  blocks: Block[],
+  stepPathMap: Record<string, string>,
+) {
+  for (const block of blocks) {
+    // Handle language-specific step content
+    if (block.step) {
+      const step = block.step;
+      await resolveLanguageSpecificStepContentFromStep(
+        parentPath,
+        step,
+        block.name,
+        stepPathMap,
+      );
+    }
+    // Handle conditional blocks
+    if (block.conditional) {
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.conditional.if?.blocks ?? [],
+        stepPathMap,
+      );
+      for (const elseIfBlock of block.conditional.elseIf) {
+        await resolveLanguageSpecificStepContentFromBlocks(
+          parentPath,
+          elseIfBlock.blocks,
+          stepPathMap,
+        );
+      }
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.conditional.else?.blocks ?? [],
+        stepPathMap,
+      );
+    }
+    // Handle loop blocks
+    await resolveLanguageSpecificStepContentFromBlocks(
+      parentPath,
+      block.loop?.blocks ?? [],
+      stepPathMap,
+    );
+    // Handle try-catch blocks
+    if (block.tryCatch) {
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.tryCatch.try?.blocks ?? [],
+        stepPathMap,
+      );
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.tryCatch.catch?.blocks ?? [],
+        stepPathMap,
+      );
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.tryCatch.finally?.blocks ?? [],
+        stepPathMap,
+      );
+    }
+    // Handle parallel blocks
+    if (block.parallel) {
+      for (const path of Object.values(block.parallel?.static?.paths ?? {})) {
+        await resolveLanguageSpecificStepContentFromBlocks(
+          parentPath,
+          path.blocks,
+          stepPathMap,
+        );
+      }
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.parallel?.dynamic?.blocks ?? [],
+        stepPathMap,
+      );
+    }
+    // Handle stream blocks
+    if (block.stream) {
+      await resolveLanguageSpecificStepContentFromBlocks(
+        parentPath,
+        block.stream.process?.blocks ?? [],
+        stepPathMap,
+      );
+      await resolveLanguageSpecificStepContentFromStep(
+        parentPath,
+        block.stream.trigger?.step ?? ({} as Step),
+        block.stream.trigger?.name,
+        stepPathMap,
+      );
+    }
+  }
+}
+
+async function resolveLanguageSpecificStepContentFromStep(
+  parentPath: string,
+  step: Step,
+  stepName?: string,
+  stepPathMap?: Record<string, string>,
+) {
+  // Handle language-specific step content
+  if (
+    !step?.integration ||
+    !LANGUAGE_STEP_EXTENSIONS[
+      step.integration as keyof typeof LANGUAGE_STEP_EXTENSIONS
+    ]
+  ) {
+    return;
+  }
+  const languageContent = step[
+    step.integration as keyof Step
+  ] as LanguageContent;
+  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) {
+        if (stepPathMap && stepName) {
+          stepPathMap[stepName] = languageContent.body.path;
+        }
+        languageContent.body = stepBodyContent;
+      }
+    }
+  }
+}
+
+export async function writeApiFiles(
+  api: ApiWrapper,
+  apiNameSlug: string,
+  directoryPath: string,
+  nestedApiFiles: boolean,
+  apiPromises: Array<Promise<void>>,
+  additionalStepFiles: AdditionalStepFiles[],
+  apiRepresentation?: ApiRepresentation,
+  existingFilePaths?: Set<string>,
+  stepPathMap?: Record<string, string>,
+) {
+  let pathForApiFile = directoryPath;
+  let yamlFileName = `${apiNameSlug}.yaml`;
+
+  const currentStepNames: string[] = [];
+  // Determine whether to extract into separate files  the source code from the steps
+  const updatedApi = extractAdditionalStepFiles(
+    api.apiPb,
+    additionalStepFiles,
+    stepPathMap ?? {},
+    currentStepNames,
+    apiRepresentation,
+  );
+
+  // Stop tracking unused step paths from removed steps (e.g. when a step is renamed or removed)
+  if (stepPathMap) {
+    Object.keys(stepPathMap).forEach((stepName) => {
+      if (!currentStepNames.includes(stepName)) {
+        const stepFileName = stepPathMap[stepName].startsWith("./")
+          ? stepPathMap[stepName].split("./")[1]
+          : stepPathMap[stepName];
+        fs.remove(`${pathForApiFile}/${stepFileName}`);
+        delete stepPathMap[stepName];
+      }
+    });
+  }
+
+  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);
+}
+
+export async function readAppApiYamlFile(
+  parentDirectory: string,
+  apiName?: string,
+): Promise<{ api: Api; stepPathMap: Record<string, string> }> {
+  // 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: string;
+  let yamlParentPath: string;
+  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)) as Api;
+
+  // Map step name -> step path
+  const stepPathMap: Record<string, string> = {};
+
+  // 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 ?? [],
+    stepPathMap,
+  );
+  return { api: apiDefn, stepPathMap };
+}

package/src/api-files/constants.ts

@@ -0,0 +1,6 @@
+export const LANGUAGE_STEP_EXTENSIONS = {
+  javascript: "js",
+  python: "py",
+} as const;
+
+export const DEFAULT_LINES_FOR_LARGE_STEPS = 1;