@knocklabs/cli 0.1.4 → 0.1.6

package/dist/lib/marshal/email-layout/reader.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    readAllForCommandTarget: ()=>readAllForCommandTarget,
+    readEmailLayoutDir: ()=>readEmailLayoutDir
+});
+const _nodePath = /*#__PURE__*/ _interopRequireDefault(require("node:path"));
+const _core = require("@oclif/core");
+const _fsExtra = /*#__PURE__*/ _interopRequireWildcard(require("fs-extra"));
+const _lodash = require("lodash");
+const _error = require("../../helpers/error");
+const _json = require("../../helpers/json");
+const _object = require("../../helpers/object");
+const _helpers = require("../shared/helpers");
+const _helpers1 = require("./helpers");
+function _interopRequireDefault(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interopRequireWildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {};
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+const readAllForCommandTarget = async (target, opts = {})=>{
+    const { type: targetType , context: targetCtx  } = target;
+    if (!targetCtx.exists) {
+        const subject = targetType === "emailLayoutDir" ? "a layout directory at" : "layout directories in";
+        return _core.ux.error(`Cannot locate ${subject} \`${targetCtx.abspath}\``);
+    }
+    switch(targetType){
+        case "emailLayoutDir":
+            {
+                return readEmailLayoutsDirs([
+                    targetCtx
+                ], opts);
+            }
+        case "emailLayoutsIndexDir":
+            {
+                const dirents = await _fsExtra.readdir(targetCtx.abspath, {
+                    withFileTypes: true
+                });
+                const promises = dirents.map(async (dirent)=>{
+                    const abspath = _nodePath.default.resolve(targetCtx.abspath, dirent.name);
+                    const layoutDirCtx = {
+                        type: "email_layout",
+                        key: dirent.name,
+                        abspath,
+                        exists: await (0, _helpers1.isEmailLayoutDir)(abspath)
+                    };
+                    return layoutDirCtx;
+                });
+                const layoutDirCtxs = (await Promise.all(promises)).filter((layoutDirCtx)=>layoutDirCtx.exists);
+                return readEmailLayoutsDirs(layoutDirCtxs, opts);
+            }
+        default:
+            throw new Error(`Invalid layout command target: ${target}`);
+    }
+};
+/*
+ * For the given list of layout directory contexts, read each layout dir and
+ * return layout directory data.
+ */ const readEmailLayoutsDirs = async (layoutDirCtxs, opts = {})=>{
+    const layouts = [];
+    const errors = [];
+    for (const layoutDirCtx of layoutDirCtxs){
+        // eslint-disable-next-line no-await-in-loop
+        const [layout, readErrors] = await readEmailLayoutDir(layoutDirCtx, opts);
+        if (readErrors.length > 0) {
+            const layoutJsonPath = _nodePath.default.resolve(layoutDirCtx.abspath, _helpers1.LAYOUT_JSON);
+            const e = new _error.SourceError((0, _error.formatErrors)(readErrors), layoutJsonPath);
+            errors.push(e);
+            continue;
+        }
+        layouts.push({
+            ...layoutDirCtx,
+            content: layout
+        });
+    }
+    return [
+        layouts,
+        errors
+    ];
+};
+const readEmailLayoutDir = async (layoutDirCtx, opts = {})=>{
+    const { abspath  } = layoutDirCtx;
+    const { withExtractedFiles =false , withReadonlyField =false  } = opts;
+    const dirExists = await _fsExtra.pathExists(abspath);
+    if (!dirExists) throw new Error(`${abspath} does not exist`);
+    const layoutJsonPath = await (0, _helpers1.lsEmailLayoutJson)(abspath);
+    if (!layoutJsonPath) throw new Error(`${abspath} is not a layout directory`);
+    const result = await (0, _json.readJson)(layoutJsonPath);
+    if (!result[0]) return result;
+    let [layoutJson] = result;
+    layoutJson = withReadonlyField ? layoutJson : (0, _object.omitDeep)(layoutJson, [
+        "__readonly"
+    ]);
+    return withExtractedFiles ? joinExtractedFiles(layoutDirCtx, layoutJson) : [
+        layoutJson,
+        []
+    ];
+};
+/*
+ * Given a layout json object, compiles all referenced extracted files from it
+ * and returns the updated object with the extracted content joined and inlined.
+ */ const joinExtractedFiles = async (layoutDirCtx, layoutJson)=>{
+    // Tracks any errors encountered during traversal. Mutated in place.
+    const errors = [];
+    // Tracks each new valid extracted file path seen (rebased to be relative to
+    // layout.json) in the layout json node. Mutated in place, and used
+    // to validate the uniqueness of an extracted path encountered.
+    const uniqueFilePaths = {};
+    (0, _object.mapValuesDeep)(layoutJson, (relpath, key, parts)=>{
+        // If not marked with the @suffix, there's nothing to do.
+        if (!_helpers.FILEPATH_MARKED_RE.test(key)) return;
+        const objPathToFieldStr = _object.ObjPath.stringify(parts);
+        const inlinObjPathStr = objPathToFieldStr.replace(_helpers.FILEPATH_MARKED_RE, "");
+        // If there is inlined content present already, then nothing more to do.
+        if ((0, _lodash.hasIn)(layoutJson, inlinObjPathStr)) return;
+        // Check if the extracted path found at the current field path is valid
+        const invalidFilePathError = (0, _helpers.validateExtractedFilePath)(relpath, _nodePath.default.resolve(layoutDirCtx.abspath, _helpers1.LAYOUT_JSON), uniqueFilePaths, objPathToFieldStr);
+        if (invalidFilePathError) {
+            errors.push(invalidFilePathError);
+            // Wipe the invalid file path in the node so the final layout json
+            // object ends up with only valid file paths, this way layout writer
+            // can see only valid file paths and use those when pulling.
+            (0, _lodash.set)(layoutJson, inlinObjPathStr, undefined);
+            (0, _lodash.set)(layoutJson, objPathToFieldStr, undefined);
+            return;
+        }
+        // By this point we have a valid extracted file path, so attempt to read the file.
+        const [content, readExtractedFileError] = (0, _helpers.readExtractedFileSync)(relpath, layoutDirCtx, key);
+        if (readExtractedFileError) {
+            errors.push(readExtractedFileError);
+            // If there's an error, replace the extracted file path with the original one, and set the
+            // inlined field path in layout object with empty content, so we know
+            // we do not need to try inlining again.
+            (0, _lodash.set)(layoutJson, objPathToFieldStr, relpath);
+            (0, _lodash.set)(layoutJson, inlinObjPathStr, undefined);
+            return;
+        }
+        // Inline the file content and remove the extracted file path.
+        (0, _lodash.set)(layoutJson, objPathToFieldStr, relpath);
+        (0, _lodash.set)(layoutJson, inlinObjPathStr, content);
+    });
+    return [
+        layoutJson,
+        errors
+    ];
+};

package/dist/lib/marshal/email-layout/types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/lib/marshal/email-layout/writer.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    writeEmailLayoutDirFromData: ()=>writeEmailLayoutDirFromData,
+    writeEmailLayoutIndexDir: ()=>writeEmailLayoutIndexDir,
+    buildEmailLayoutDirBundle: ()=>buildEmailLayoutDirBundle,
+    pruneLayoutsIndexDir: ()=>pruneLayoutsIndexDir,
+    toEmailLayoutJson: ()=>toEmailLayoutJson
+});
+const _nodePath = /*#__PURE__*/ _interopRequireDefault(require("node:path"));
+const _fsExtra = /*#__PURE__*/ _interopRequireWildcard(require("fs-extra"));
+const _lodash = require("lodash");
+const _const = require("../../helpers/const");
+const _json = require("../../helpers/json");
+const _object = require("../../helpers/object");
+const _helpers = require("../shared/helpers");
+const _helpers1 = require("./helpers");
+const _reader = require("./reader");
+function _interopRequireDefault(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interopRequireWildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {};
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+/* Traverse a given email layout data and compile extraction settings of every extractable
+ * field into a sorted map.
+ *
+ * NOTE: Currently we do NOT support content extraction at nested levels for email layouts.
+ */ const compileExtractionSettings = (emailLayout)=>{
+    const extractableFields = (0, _lodash.get)(emailLayout, [
+        "__annotation",
+        "extractable_fields"
+    ], {});
+    const map = new Map();
+    for (const [key] of Object.entries(emailLayout)){
+        // If the field we are on is extractable, then add its extraction
+        // settings to the map with the current object path.
+        if (key in extractableFields) {
+            map.set([
+                key
+            ], extractableFields[key]);
+        }
+    }
+    return map;
+};
+/* Sanitize the email layout content into a format that's appropriate for reading
+ * and writing, by stripping out any annotation fields and handling readonly
+ * fields.
+ */ const toEmailLayoutJson = (emailLayout)=>{
+    var _emailLayout___annotation;
+    // Move read only field under the dedicated field "__readonly".
+    const readonlyFields = ((_emailLayout___annotation = emailLayout.__annotation) === null || _emailLayout___annotation === void 0 ? void 0 : _emailLayout___annotation.readonly_fields) || [];
+    const [readonly, remainder] = (0, _object.split)(emailLayout, readonlyFields);
+    const emailLayoutjson = {
+        ...remainder,
+        __readonly: readonly
+    };
+    // Strip out all schema annotations, so not to expose them to end users.
+    return (0, _object.omitDeep)(emailLayoutjson, [
+        "__annotation"
+    ]);
+};
+const writeEmailLayoutDirFromData = async (emailLayoutDirCtx, remoteEmailLayout)=>{
+    // If the layout directory exists on the file system (i.e. previously
+    // pulled before), then read the layout file to use as a reference.
+    const [localEmailLayout] = emailLayoutDirCtx.exists ? await (0, _reader.readEmailLayoutDir)(emailLayoutDirCtx, {
+        withExtractedFiles: true
+    }) : [];
+    const bundle = buildEmailLayoutDirBundle(remoteEmailLayout, localEmailLayout);
+    const backupDirPath = _nodePath.default.resolve(_const.sandboxDir, (0, _lodash.uniqueId)("backup"));
+    try {
+        // We store a backup in case there's an error.
+        if (emailLayoutDirCtx.exists) {
+            await _fsExtra.copy(emailLayoutDirCtx.abspath, backupDirPath);
+            await _fsExtra.emptyDir(emailLayoutDirCtx.abspath);
+        }
+        const promises = Object.entries(bundle).map(([relpath, fileContent])=>{
+            const filePath = _nodePath.default.resolve(emailLayoutDirCtx.abspath, relpath);
+            return relpath === _helpers1.LAYOUT_JSON ? _fsExtra.outputJson(filePath, fileContent, {
+                spaces: _json.DOUBLE_SPACES
+            }) : _fsExtra.outputFile(filePath, fileContent);
+        });
+        await Promise.all(promises);
+    } catch (error) {
+        // In case of any error, wipe the target directory that is likely in a bad
+        // state then restore the backup if one existed before.
+        if (emailLayoutDirCtx.exists) {
+            await _fsExtra.emptyDir(emailLayoutDirCtx.abspath);
+            await _fsExtra.copy(backupDirPath, emailLayoutDirCtx.abspath);
+        } else {
+            await _fsExtra.remove(emailLayoutDirCtx.abspath);
+        }
+        throw error;
+    } finally{
+        // Always clean up the backup directory in the temp sandbox.
+        await _fsExtra.remove(backupDirPath);
+    }
+};
+/* For a given email layout payload, this function builds a "email layout directoy bundle".
+ * This is an object which contains all the relative paths and its file content.
+ * It includes the extractable fields, which are extracted out and added to the bundle as separate files.
+ */ const buildEmailLayoutDirBundle = (remoteEmailLayout, localEmailLayout = {})=>{
+    const bundle = {};
+    const mutRemoteEmailLayout = (0, _lodash.cloneDeep)(remoteEmailLayout);
+    // A map of extraction settings of every field in the email layout
+    const compiledExtractionSettings = compileExtractionSettings(mutRemoteEmailLayout);
+    // Iterate through each extractable field, determine whether we need to
+    // extract the field content, and if so, perform the
+    // extraction.
+    for (const [objPathParts, extractionSettings] of compiledExtractionSettings){
+        // If this layout doesn't have this field path, then we don't extract.
+        if (!(0, _lodash.has)(mutRemoteEmailLayout, objPathParts)) continue;
+        // If the field at this path is extracted in the local layout, then
+        // always extract; otherwise extract based on the field settings default.
+        const objPathStr = _object.ObjPath.stringify(objPathParts);
+        const extractedFilePath = (0, _lodash.get)(localEmailLayout, `${objPathStr}${_helpers.FILEPATH_MARKER}`);
+        const { default: extractByDefault , file_ext: fileExt  } = extractionSettings;
+        if (!extractedFilePath && !extractByDefault) continue;
+        // By this point, we have a field where we need to extract its content.
+        const data = (0, _lodash.get)(mutRemoteEmailLayout, objPathParts);
+        const fileName = objPathParts.pop();
+        // If we have an extracted file path from the local layout, we use that. In the other
+        // case we use the default path.
+        const relpath = typeof extractedFilePath === "string" ? extractedFilePath : `${fileName}.${fileExt}`;
+        // Perform the extraction by adding the content and its file path to the
+        // bundle for writing to the file system later. Then replace the field
+        // content with the extracted file path and mark the field as extracted
+        // with @ suffix.
+        (0, _lodash.set)(bundle, [
+            relpath
+        ], data);
+        (0, _lodash.set)(mutRemoteEmailLayout, `${objPathStr}${_helpers.FILEPATH_MARKER}`, relpath);
+        (0, _lodash.unset)(mutRemoteEmailLayout, objPathStr);
+    }
+    // At this point the bundle contains all extractable files, so we finally add the layout
+    // JSON realtive path + the file content.
+    return (0, _lodash.set)(bundle, [
+        _helpers1.LAYOUT_JSON
+    ], toEmailLayoutJson(mutRemoteEmailLayout));
+};
+const writeEmailLayoutIndexDir = async (indexDirCtx, remoteEmailLayouts)=>{
+    const backupDirPath = _nodePath.default.resolve(_const.sandboxDir, (0, _lodash.uniqueId)("backup"));
+    try {
+        if (indexDirCtx.exists) {
+            await _fsExtra.copy(indexDirCtx.abspath, backupDirPath);
+            await pruneLayoutsIndexDir(indexDirCtx, remoteEmailLayouts);
+        }
+        const writeEmailLayoutDirPromises = remoteEmailLayouts.map(async (remoteEmailLayout)=>{
+            const emailLayoutDirPath = _nodePath.default.resolve(indexDirCtx.abspath, remoteEmailLayout.key);
+            const emailLayoutDirCtx = {
+                type: "email_layout",
+                key: remoteEmailLayout.key,
+                abspath: emailLayoutDirPath,
+                exists: indexDirCtx.exists ? await (0, _helpers1.isEmailLayoutDir)(emailLayoutDirPath) : false
+            };
+            return writeEmailLayoutDirFromData(emailLayoutDirCtx, remoteEmailLayout);
+        });
+        await Promise.all(writeEmailLayoutDirPromises);
+    } catch (error) {
+        if (indexDirCtx.exists) {
+            await _fsExtra.emptyDir(indexDirCtx.abspath);
+            await _fsExtra.copy(backupDirPath, indexDirCtx.abspath);
+        } else {
+            await _fsExtra.remove(indexDirCtx.abspath);
+        }
+        throw error;
+    } finally{
+        // Always clean up the backup directory in the temp sandbox.
+        await _fsExtra.remove(backupDirPath);
+    }
+};
+/*
+ * Prunes the index directory by removing any files, or directories that aren't
+ * layout dirs found in fetched layouts. We want to preserve any layout
+ * dirs that are going to be updated with remote layouts, so extracted links
+ * can be respected.
+ */ const pruneLayoutsIndexDir = async (indexDirCtx, remoteEmailLayouts)=>{
+    const emailLayoutsByKey = Object.fromEntries(remoteEmailLayouts.map((e)=>[
+            e.key.toLowerCase(),
+            e
+        ]));
+    const dirents = await _fsExtra.readdir(indexDirCtx.abspath, {
+        withFileTypes: true
+    });
+    const promises = dirents.map(async (dirent)=>{
+        const direntName = dirent.name.toLowerCase();
+        const direntPath = _nodePath.default.resolve(indexDirCtx.abspath, direntName);
+        if (await (0, _helpers1.isEmailLayoutDir)(direntPath) && emailLayoutsByKey[direntName]) {
+            return;
+        }
+        await _fsExtra.remove(direntPath);
+    });
+    await Promise.all(promises);
+};

package/dist/lib/marshal/shared/helpers.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    FILEPATH_MARKER: ()=>FILEPATH_MARKER,
+    FILEPATH_MARKED_RE: ()=>FILEPATH_MARKED_RE,
+    readExtractedFileSync: ()=>readExtractedFileSync,
+    validateExtractedFilePath: ()=>validateExtractedFilePath,
+    checkIfValidExtractedFilePathFormat: ()=>checkIfValidExtractedFilePathFormat
+});
+const _nodePath = /*#__PURE__*/ _interopRequireWildcard(require("node:path"));
+const _fsExtra = /*#__PURE__*/ _interopRequireWildcard(require("fs-extra"));
+const _error = require("../../helpers/error");
+const _json = require("../../helpers/json");
+const _liquid = require("../../helpers/liquid");
+const _workflow = require("../workflow");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interopRequireWildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {};
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+const FILEPATH_MARKER = "@";
+const FILEPATH_MARKED_RE = new RegExp(`${FILEPATH_MARKER}$`);
+// The following files are exepected to have valid json content, and should be
+// decoded and joined into the main JSON file.
+const DECODABLE_JSON_FILES = new Set([
+    _workflow.VISUAL_BLOCKS_JSON
+]);
+const readExtractedFileSync = (relpath, dirCtx, objPathToFieldStr = "")=>{
+    // Check if the file actually exists at the given file path.
+    const abspath = _nodePath.resolve(dirCtx.abspath, relpath);
+    const exists = _fsExtra.pathExistsSync(abspath);
+    if (!exists) {
+        const error = new _error.JsonDataError("must be a relative path string to a file that exists", objPathToFieldStr);
+        return [
+            undefined,
+            error
+        ];
+    }
+    // Read the file and check for valid liquid syntax given it is supported
+    // across all message templates and file extensions.
+    const contentStr = _fsExtra.readFileSync(abspath, "utf8");
+    const liquidParseError = (0, _liquid.validateLiquidSyntax)(contentStr);
+    if (liquidParseError) {
+        const error = new _error.JsonDataError(`points to a file that contains invalid liquid syntax (${relpath})\n\n` + (0, _error.formatErrors)([
+            liquidParseError
+        ], {
+            indentBy: 2
+        }), objPathToFieldStr);
+        return [
+            undefined,
+            error
+        ];
+    }
+    // If the file is expected to contain decodable json, then parse the contentStr
+    // as such.
+    const fileName = _nodePath.basename(abspath.toLowerCase());
+    const decodable = DECODABLE_JSON_FILES.has(fileName);
+    const [content, jsonParseErrors] = decodable ? (0, _json.parseJson)(contentStr) : [
+        contentStr,
+        []
+    ];
+    if (jsonParseErrors.length > 0) {
+        const error = new _error.JsonDataError(`points to a file with invalid content (${relpath})\n\n` + (0, _error.formatErrors)(jsonParseErrors, {
+            indentBy: 2
+        }), objPathToFieldStr);
+        return [
+            undefined,
+            error
+        ];
+    }
+    return [
+        content,
+        undefined
+    ];
+};
+const validateExtractedFilePath = (val, sourceFileAbspath, uniqueFilePaths, objPathToFieldStr)=>{
+    // Validate the file path format, and that it is unique per entity.
+    if (!checkIfValidExtractedFilePathFormat(val, sourceFileAbspath) || typeof val !== "string" || val in uniqueFilePaths) {
+        const error = new _error.JsonDataError("must be a relative path string to a unique file within the directory", objPathToFieldStr);
+        return error;
+    }
+    // Keep track of all the valid extracted file paths that have been seen, so
+    // we can validate each file path's uniqueness as we traverse.
+    uniqueFilePaths[val] = true;
+    return undefined;
+};
+const checkIfValidExtractedFilePathFormat = (relpath, sourceFileAbspath)=>{
+    if (typeof relpath !== "string") return false;
+    if (_nodePath.isAbsolute(relpath)) return false;
+    const extractedFileAbspath = _nodePath.resolve(sourceFileAbspath, relpath);
+    const pathDiff = _nodePath.relative(sourceFileAbspath, extractedFileAbspath);
+    return !pathDiff.startsWith("..");
+};

package/dist/lib/marshal/workflow/generator.js

@@ -15,7 +15,8 @@ _export(exports, {
 });
 const _nodePath = /*#__PURE__*/ _interopRequireWildcard(require("node:path"));
 const _lodash = require("lodash");
-const _helpers = require("./helpers");
+const _helpers = require("../shared/helpers");
+const _helpers1 = require("./helpers");
 const _types = require("./types");
 const _writer = require("./writer");
 function _getRequireWildcardCache(nodeInterop) {
@@ -263,7 +264,7 @@ const scaffoldWorkflowDirBundle = (attrs)=>{
         steps: scaffoldedSteps
     };
     return (0, _lodash.assign)({
-        [_helpers.WORKFLOW_JSON]: workflowJson
+        [_helpers1.WORKFLOW_JSON]: workflowJson
     }, ...bundleFragments);
 };
 const generateWorkflowDir = async (workflowDirCtx, attrs)=>{

package/dist/lib/marshal/workflow/helpers.js

@@ -12,15 +12,14 @@ _export(exports, {
     WORKFLOW_JSON: ()=>WORKFLOW_JSON,
     VISUAL_BLOCKS_JSON: ()=>VISUAL_BLOCKS_JSON,
     workflowJsonPath: ()=>workflowJsonPath,
-    FILEPATH_MARKER: ()=>FILEPATH_MARKER,
-    FILEPATH_MARKED_RE: ()=>FILEPATH_MARKED_RE,
     validateWorkflowKey: ()=>validateWorkflowKey,
     lsWorkflowJson: ()=>lsWorkflowJson,
     isWorkflowDir: ()=>isWorkflowDir,
     formatCategories: ()=>formatCategories,
     formatStepSummary: ()=>formatStepSummary,
     formatStatus: ()=>formatStatus,
-    ensureValidCommandTarget: ()=>ensureValidCommandTarget
+    ensureValidCommandTarget: ()=>ensureValidCommandTarget,
+    countSteps: ()=>countSteps
 });
 const _nodePath = /*#__PURE__*/ _interopRequireWildcard(require("node:path"));
 const _core = require("@oclif/core");
@@ -70,8 +69,6 @@ function _interopRequireWildcard(obj, nodeInterop) {
 const WORKFLOW_JSON = "workflow.json";
 const VISUAL_BLOCKS_JSON = "visual_blocks.json";
 const workflowJsonPath = (workflowDirCtx)=>_nodePath.resolve(workflowDirCtx.abspath, WORKFLOW_JSON);
-const FILEPATH_MARKER = "@";
-const FILEPATH_MARKED_RE = new RegExp(`${FILEPATH_MARKER}$`);
 const validateWorkflowKey = (input)=>{
     if (!(0, _string.checkSlugifiedFormat)(input, {
         onlyLowerCase: true
@@ -126,6 +123,17 @@ const throttleStepSummaryLines = (step)=>{
         `Throttle limit: ${throttle_limit}`
     ];
 };
+const branchStepSummaryLines = (step)=>{
+    if (step.type !== _types.StepType.Branch) return [];
+    let stepsCount = 0;
+    for (const branch of step.branches){
+        stepsCount += doCountSteps(branch.steps);
+    }
+    return [
+        `Branches: ${step.branches.length}`,
+        `Steps: ${stepsCount}`
+    ];
+};
 const delayStepSummaryLines = (step)=>{
     if (step.type !== _types.StepType.Delay) return [];
     const { delay_for: duration , delay_until_field_path: field_path  } = step.settings;
@@ -157,6 +165,7 @@ const formatStepSummary = (step)=>{
         ...batchStepSummaryLines(step),
         ...delayStepSummaryLines(step),
         ...httpFetchStepSummaryLines(step),
+        ...branchStepSummaryLines(step),
         ...throttleStepSummaryLines(step),
         // Extra line between step rows to make it easier on the eye.
         " "
@@ -224,3 +233,16 @@ const ensureValidCommandTarget = async (props, runContext)=>{
     }
     return _core.ux.error("Missing 1 required arg:\nworkflowKey");
 };
+const doCountSteps = (steps)=>{
+    let count = 0;
+    for (const step of steps){
+        count += 1;
+        if (step.type === _types.StepType.Branch) {
+            for (const branch of step.branches){
+                count += doCountSteps(branch.steps);
+            }
+        }
+    }
+    return count;
+};
+const countSteps = (workflow)=>doCountSteps(workflow.steps);