@knocklabs/cli 0.1.21 → 0.1.23

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

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ensureValidCommandTarget () {
+        return ensureValidCommandTarget;
+    },
+    get formatActivationRules () {
+        return formatActivationRules;
+    },
+    get formatStatusWithSchedule () {
+        return formatStatusWithSchedule;
+    },
+    get formatStep () {
+        return formatStep;
+    },
+    get generateIndexTypeTS () {
+        return generateIndexTypeTS;
+    },
+    get generateTypes () {
+        return generateTypes;
+    },
+    get guideJsonPath () {
+        return guideJsonPath;
+    },
+    get isGuideDir () {
+        return isGuideDir;
+    },
+    get lsGuideJson () {
+        return lsGuideJson;
+    }
+});
+const _nodepath = /*#__PURE__*/ _interop_require_wildcard(require("node:path"));
+const _core = require("@oclif/core");
+const _fsextra = /*#__PURE__*/ _interop_require_wildcard(require("fs-extra"));
+const _lodash = require("lodash");
+const _quicktypecore = require("quicktype-core");
+const _processorisomorphic = require("./processor.isomorphic");
+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 _interop_require_wildcard(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 = {
+        __proto__: null
+    };
+    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 formatStatusWithSchedule = (guide)=>{
+    const baseStatus = guide.active ? "Active" : "Inactive";
+    if (guide.active_from || guide.active_until) {
+        const fromText = guide.active_from ? `from ${guide.active_from}` : "immediately";
+        const untilText = guide.active_until ? `until ${guide.active_until}` : "with no end time";
+        return `${baseStatus} (${fromText} ${untilText})`;
+    }
+    return baseStatus;
+};
+const formatStep = (step)=>{
+    return `${step.schema_key} (${step.schema_variant_key})`;
+};
+const formatActivationRules = (rules)=>{
+    if (!rules || !Array.isArray(rules)) return "-";
+    return rules.map(({ directive, pathname })=>`${directive} ${pathname}`).join(", ");
+};
+const guideJsonPath = (guideDirCtx)=>_nodepath.resolve(guideDirCtx.abspath, _processorisomorphic.GUIDE_JSON);
+const lsGuideJson = async (dirPath)=>{
+    const guideJsonPath = _nodepath.resolve(dirPath, _processorisomorphic.GUIDE_JSON);
+    const exists = await _fsextra.pathExists(guideJsonPath);
+    return exists ? guideJsonPath : undefined;
+};
+const isGuideDir = async (dirPath)=>Boolean(await lsGuideJson(dirPath));
+const ensureValidCommandTarget = async (props, runContext)=>{
+    const { args, flags } = props;
+    const { commandId, resourceDir: resourceDirCtx, cwd: runCwd } = runContext;
+    // If the target resource is a different type than the current resource dir
+    // type, error out.
+    if (resourceDirCtx && resourceDirCtx.type !== "guide") {
+        return _core.ux.error(`Cannot run ${commandId} inside a ${resourceDirCtx.type} directory`);
+    }
+    // Cannot accept both guide key arg and --all flag.
+    if (flags.all && args.guideKey) {
+        return _core.ux.error(`guideKey arg \`${args.guideKey}\` cannot also be provided when using --all`);
+    }
+    // --all flag is given, which means no guide key arg.
+    if (flags.all) {
+        // If --all flag used inside a guide directory, then require a guides
+        // dir path.
+        if (resourceDirCtx && !flags["guides-dir"]) {
+            return _core.ux.error("Missing required flag guides-dir");
+        }
+        // Targeting all guide dirs in the guides index dir.
+        // TODO: Default to the knock project config first if present before cwd.
+        const defaultToCwd = {
+            abspath: runCwd,
+            exists: true
+        };
+        const indexDirCtx = flags["guides-dir"] || defaultToCwd;
+        return {
+            type: "guidesIndexDir",
+            context: indexDirCtx
+        };
+    }
+    // Guide key arg is given, which means no --all flag.
+    if (args.guideKey) {
+        if (resourceDirCtx && resourceDirCtx.key !== args.guideKey) {
+            return _core.ux.error(`Cannot run ${commandId} \`${args.guideKey}\` inside another guide directory:\n${resourceDirCtx.key}`);
+        }
+        const targetDirPath = resourceDirCtx ? resourceDirCtx.abspath : _nodepath.resolve(runCwd, args.guideKey);
+        const guideDirCtx = {
+            type: "guide",
+            key: args.guideKey,
+            abspath: targetDirPath,
+            exists: await isGuideDir(targetDirPath)
+        };
+        return {
+            type: "guideDir",
+            context: guideDirCtx
+        };
+    }
+    // From this point on, we have neither a guide key arg nor --all flag.
+    // If running inside a guide directory, then use that guide directory.
+    if (resourceDirCtx) {
+        return {
+            type: "guideDir",
+            context: resourceDirCtx
+        };
+    }
+    return _core.ux.error("Missing 1 required arg:\nguideKey");
+};
+/*
+ * Takes an array of guides and generate types from its content json schemas.
+ */ const SCHEMA_TITLE_PREFIX = "Guide";
+async function generateTypes(guides, targetLanguage) {
+    const schemaInput = new _quicktypecore.JSONSchemaInput(new _quicktypecore.FetchingJSONSchemaStore());
+    let processedCount = 0;
+    const mapping = {
+        key: {},
+        type: {}
+    };
+    for (const guide of guides){
+        if (!guide.type) {
+            continue;
+        }
+        // We only support single step guides at the moment.
+        const step = (guide.steps || []).find((s)=>s.json_schema);
+        if (!step) {
+            continue;
+        }
+        // Format the type name that quicktype can output exactly. It's important
+        // that the names we format are used/preserved by quicktype as we create the
+        // final mapping referencing these type names.
+        // Example: `GuideBannerFourStep1Banner001Default`
+        const typeName = [
+            SCHEMA_TITLE_PREFIX,
+            startCaseNoSpace(guide.key),
+            startCaseNoSpace(step.ref),
+            startCaseNoSpace(step.schema_key),
+            startCaseNoSpace(step.schema_semver),
+            startCaseNoSpace(step.schema_variant_key)
+        ].join("");
+        schemaInput.addSource({
+            name: typeName,
+            schema: JSON.stringify({
+                ...step.json_schema,
+                title: typeName
+            })
+        });
+        mapping.key[guide.key] = typeName;
+        mapping.type[guide.type] = [
+            ...mapping.type[guide.type] || [],
+            typeName
+        ];
+        processedCount++;
+    }
+    if (processedCount === 0) {
+        return {
+            result: undefined,
+            count: 0,
+            mapping
+        };
+    }
+    const inputData = new _quicktypecore.InputData();
+    inputData.addInput(schemaInput);
+    const result = await (0, _quicktypecore.quicktype)({
+        inputData,
+        lang: targetLanguage,
+        allPropertiesOptional: false,
+        alphabetizeProperties: true,
+        rendererOptions: {
+            "just-types": true,
+            "no-extra-properties": true,
+            "no-optional-null": true
+        }
+    });
+    return {
+        result,
+        count: processedCount,
+        mapping
+    };
+}
+const startCaseNoSpace = (key)=>(0, _lodash.startCase)(key).replace(/\s/g, "");
+/*
+ * For typescript, this writes a root type that maps out all guide types by
+ * guide type and key.
+ *
+ * For example:
+ *   type GuideContentByType = {
+ *     "banner-one": GuideBannerOneStep1Banner001Default;
+ *     "banner-two": GuideBannerTwoStep1Banner001Default;
+ *     "card-one": GuideCardOneStep1Card001Default;
+ *     "card-two": GuideCardTwoStep1Card001SingleAction;
+ *     "changelog-card": GuideChangelogCardStep1ChangelogCard001SingleAction;
+ *     "modal-one": GuideModalOneStep1Modal001MultiAction;
+ *   };
+ *
+ *   type GuideContentByKey = {
+ *     "banner": GuideBannerOneStep1Banner001Default | GuideBannerTwoStep1Banner001Default;
+ *     "card": GuideCardOneStep1Card001Default | GuideCardTwoStep1Card001SingleAction;
+ *     "changelog-card": GuideChangelogCardStep1ChangelogCard001SingleAction;
+ *     "modal": GuideModalOneStep1Modal001MultiAction;
+ *   };
+ *
+ *   export type GuideContentIndex = {
+ *     key: GuideContentByType;
+ *     type: GuideContentByKey;
+ *   };
+ */ const TS_INDEX_TYPE_PREFIX = "GuideContent";
+const generateIndexTypeTS = (mapping)=>{
+    const lines = [];
+    // Define the type for sub index by guide key.
+    const byKey = `${TS_INDEX_TYPE_PREFIX}ByKey`;
+    lines.push(`\ntype ${byKey} = {`);
+    for (const [key, val] of Object.entries(mapping.key)){
+        lines.push(`  "${key}": ${val};`);
+    }
+    lines.push("};");
+    // Define the type for sub index by guide type.
+    const byType = `${TS_INDEX_TYPE_PREFIX}ByType`;
+    lines.push(`\ntype ${byType} = {`);
+    for (const [key, val] of Object.entries(mapping.type)){
+        lines.push(`  "${key}": ${(val || []).join(" | ")};`);
+    }
+    lines.push("};", `\nexport type ${TS_INDEX_TYPE_PREFIX}Index = {`, `  key: ${byKey};`, `  type: ${byType};`, "};");
+    return lines;
+};

package/dist/lib/marshal/guide/index.js

@@ -2,8 +2,11 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
+_export_star(require("./helpers"), exports);
 _export_star(require("./processor.isomorphic"), exports);
+_export_star(require("./reader"), exports);
 _export_star(require("./types"), exports);
+_export_star(require("./writer"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

package/dist/lib/marshal/guide/processor.isomorphic.js

@@ -12,14 +12,14 @@ Object.defineProperty(exports, "__esModule", {
 function _export(target, all) {
     for(var name in all)Object.defineProperty(target, name, {
         enumerable: true,
-        get: all[name]
+        get: Object.getOwnPropertyDescriptor(all, name).get
     });
 }
 _export(exports, {
-    GUIDE_JSON: function() {
+    get GUIDE_JSON () {
         return GUIDE_JSON;
     },
-    buildGuideDirBundle: function() {
+    get buildGuideDirBundle () {
         return buildGuideDirBundle;
     }
 });

package/dist/lib/marshal/guide/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: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get readAllForCommandTarget () {
+        return readAllForCommandTarget;
+    },
+    get readGuideDir () {
+        return readGuideDir;
+    }
+});
+const _nodepath = /*#__PURE__*/ _interop_require_wildcard(require("node:path"));
+const _core = require("@oclif/core");
+const _fsextra = /*#__PURE__*/ _interop_require_wildcard(require("fs-extra"));
+const _lodash = require("lodash");
+const _error = require("../../helpers/error");
+const _json = require("../../helpers/json");
+const _objectisomorphic = require("../../helpers/object.isomorphic");
+const _constisomorphic = require("../shared/const.isomorphic");
+const _helpers = require("../shared/helpers");
+const _helpers1 = require("./helpers");
+const _processorisomorphic = require("./processor.isomorphic");
+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 _interop_require_wildcard(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 = {
+        __proto__: null
+    };
+    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;
+}
+/*
+ * For the given list of guide directory contexts, read each guide dir and
+ * return guide directory data.
+ */ const readGuideDirs = async (guideDirCtxs, opts = {})=>{
+    const guides = [];
+    const errors = [];
+    for (const guideDirCtx of guideDirCtxs){
+        // eslint-disable-next-line no-await-in-loop
+        const [guide, readErrors] = await readGuideDir(guideDirCtx, opts);
+        if (readErrors.length > 0) {
+            const guideJsonPath = _nodepath.resolve(guideDirCtx.abspath, _processorisomorphic.GUIDE_JSON);
+            const e = new _error.SourceError((0, _error.formatErrors)(readErrors), guideJsonPath);
+            errors.push(e);
+            continue;
+        }
+        guides.push({
+            ...guideDirCtx,
+            content: guide
+        });
+    }
+    return [
+        guides,
+        errors
+    ];
+};
+const readGuideDir = async (guideDirCtx, opts = {})=>{
+    const { abspath } = guideDirCtx;
+    const { withExtractedFiles = false } = opts;
+    const dirExists = await _fsextra.pathExists(abspath);
+    if (!dirExists) throw new Error(`${abspath} does not exist`);
+    const guideJsonPath = await (0, _helpers1.lsGuideJson)(abspath);
+    if (!guideJsonPath) throw new Error(`${abspath} is not a guide directory`);
+    const result = await (0, _json.readJson)(guideJsonPath);
+    if (!result[0]) return result;
+    let [guideJson] = result;
+    guideJson = (0, _objectisomorphic.omitDeep)(guideJson, [
+        "__readonly"
+    ]);
+    return withExtractedFiles ? joinExtractedFiles(guideDirCtx, guideJson) : [
+        guideJson,
+        []
+    ];
+};
+const joinExtractedFiles = async (guideDirCtx, guideJson)=>{
+    // Tracks any errors encountered during traversal. Mutated in place.
+    const errors = [];
+    // Tracks each new valid extracted file path seen (rebased to be relative to
+    // guide.json) in the guide json node. Mutated in place, and used
+    // to validate the uniqueness of an extracted path encountered.
+    const uniqueFilePaths = {};
+    (0, _objectisomorphic.mapValuesDeep)(guideJson, (relpath, key, parts)=>{
+        // If not marked with the @suffix, there's nothing to do.
+        if (!_constisomorphic.FILEPATH_MARKED_RE.test(key)) return;
+        const objPathToFieldStr = _objectisomorphic.ObjPath.stringify(parts);
+        const inlinObjPathStr = objPathToFieldStr.replace(_constisomorphic.FILEPATH_MARKED_RE, "");
+        // If there is inlined content present already, then nothing more to do.
+        if ((0, _lodash.hasIn)(guideJson, inlinObjPathStr)) return;
+        // Check if the extracted path found at the current field path is valid
+        const invalidFilePathError = (0, _helpers.validateExtractedFilePath)(relpath, _nodepath.resolve(guideDirCtx.abspath, _processorisomorphic.GUIDE_JSON), uniqueFilePaths, objPathToFieldStr);
+        if (invalidFilePathError) {
+            errors.push(invalidFilePathError);
+            // Wipe the invalid file path in the node so the final guide json
+            // object ends up with only valid file paths, this way guide writer
+            // can see only valid file paths and use those when pulling.
+            (0, _lodash.set)(guideJson, inlinObjPathStr, undefined);
+            (0, _lodash.set)(guideJson, 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, guideDirCtx, 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 guide object with empty content, so we know
+            // we do not need to try inlining again.
+            (0, _lodash.set)(guideJson, objPathToFieldStr, relpath);
+            (0, _lodash.set)(guideJson, inlinObjPathStr, undefined);
+            return;
+        }
+        // Inline the file content and remove the extracted file path.
+        (0, _lodash.set)(guideJson, objPathToFieldStr, relpath);
+        (0, _lodash.set)(guideJson, inlinObjPathStr, content);
+    });
+    return [
+        guideJson,
+        errors
+    ];
+};
+const readAllForCommandTarget = async (target, opts = {})=>{
+    const { type: targetType, context: targetCtx } = target;
+    if (!targetCtx.exists) {
+        const subject = targetType === "guideDir" ? "a guide directory at" : "guide directories in";
+        return _core.ux.error(`Cannot locate ${subject} \`${targetCtx.abspath}\``);
+    }
+    switch(targetType){
+        case "guideDir":
+            {
+                return readGuideDirs([
+                    targetCtx
+                ], opts);
+            }
+        case "guidesIndexDir":
+            {
+                const dirents = await _fsextra.readdir(targetCtx.abspath, {
+                    withFileTypes: true
+                });
+                const promises = dirents.map(async (dirent)=>{
+                    const abspath = _nodepath.resolve(targetCtx.abspath, dirent.name);
+                    const guideDirCtx = {
+                        type: "guide",
+                        key: dirent.name,
+                        abspath,
+                        exists: await (0, _helpers1.isGuideDir)(abspath)
+                    };
+                    return guideDirCtx;
+                });
+                const guideDirCtxs = (await Promise.all(promises)).filter((guideDirCtx)=>guideDirCtx.exists);
+                return readGuideDirs(guideDirCtxs, opts);
+            }
+        default:
+            throw new Error(`Invalid guide command target: ${target}`);
+    }
+};

package/dist/lib/marshal/guide/writer.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get pruneGuidesIndexDir () {
+        return pruneGuidesIndexDir;
+    },
+    get writeGuideDirFromData () {
+        return writeGuideDirFromData;
+    },
+    get writeGuidesIndexDir () {
+        return writeGuidesIndexDir;
+    }
+});
+const _nodepath = /*#__PURE__*/ _interop_require_wildcard(require("node:path"));
+const _fsextra = /*#__PURE__*/ _interop_require_wildcard(require("fs-extra"));
+const _lodash = require("lodash");
+const _const = require("../../helpers/const");
+const _json = require("../../helpers/json");
+const _helpers = require("./helpers");
+const _processorisomorphic = require("./processor.isomorphic");
+const _reader = require("./reader");
+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 _interop_require_wildcard(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 = {
+        __proto__: null
+    };
+    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 writeGuideDirFromData = async (guideDirCtx, remoteGuide)=>{
+    // If the guide directory exists on the file system (i.e. previously
+    // pulled before), then read the guide file to use as a reference.
+    const [localGuide] = guideDirCtx.exists ? await (0, _reader.readGuideDir)(guideDirCtx, {
+        withExtractedFiles: true
+    }) : [];
+    const bundle = (0, _processorisomorphic.buildGuideDirBundle)(remoteGuide, localGuide);
+    return writeGuideDirFromBundle(guideDirCtx, bundle);
+};
+/*
+ * A lower level write function that takes a constructed guide dir bundle
+ * and writes it into a guide directory on a local file system.
+ *
+ * It does not make any assumptions about how the guide directory bundle was
+ * built; for example, it can be from parsing the guide data fetched from
+ * the Knock API, or built manually for scaffolding purposes.
+ */ const writeGuideDirFromBundle = async (guideDirCtx, guideDirBundle)=>{
+    const backupDirPath = _nodepath.resolve(_const.sandboxDir, (0, _lodash.uniqueId)("backup"));
+    try {
+        if (guideDirCtx.exists) {
+            await _fsextra.copy(guideDirCtx.abspath, backupDirPath);
+            await _fsextra.emptyDir(guideDirCtx.abspath);
+        }
+        const promises = Object.entries(guideDirBundle).map(([relpath, fileContent])=>{
+            const filePath = _nodepath.resolve(guideDirCtx.abspath, relpath);
+            return relpath === _processorisomorphic.GUIDE_JSON ? _fsextra.outputJson(filePath, fileContent, {
+                spaces: _json.DOUBLE_SPACES
+            }) : _fsextra.outputFile(filePath, fileContent !== null && fileContent !== void 0 ? 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 (guideDirCtx.exists) {
+            await _fsextra.emptyDir(guideDirCtx.abspath);
+            await _fsextra.copy(backupDirPath, guideDirCtx.abspath);
+        } else {
+            await _fsextra.remove(guideDirCtx.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
+ * guide dirs found in fetched guides. We want to preserve any guide
+ * dirs that are going to be updated with remote guides, so extracted links
+ * can be respected.
+ */ const pruneGuidesIndexDir = async (indexDirCtx, remoteGuides)=>{
+    const guidesByKey = Object.fromEntries(remoteGuides.map((w)=>[
+            w.key.toLowerCase(),
+            w
+        ]));
+    const dirents = await _fsextra.readdir(indexDirCtx.abspath, {
+        withFileTypes: true
+    });
+    const promises = dirents.map(async (dirent)=>{
+        const direntName = dirent.name.toLowerCase();
+        const direntPath = _nodepath.resolve(indexDirCtx.abspath, direntName);
+        if (await (0, _helpers.isGuideDir)(direntPath) && guidesByKey[direntName]) {
+            return;
+        }
+        await _fsextra.remove(direntPath);
+    });
+    await Promise.all(promises);
+};
+const writeGuidesIndexDir = async (indexDirCtx, remoteGuides)=>{
+    const backupDirPath = _nodepath.resolve(_const.sandboxDir, (0, _lodash.uniqueId)("backup"));
+    try {
+        // If the index directory already exists, back it up in the temp sandbox
+        // before wiping it clean.
+        if (indexDirCtx.exists) {
+            await _fsextra.copy(indexDirCtx.abspath, backupDirPath);
+            await pruneGuidesIndexDir(indexDirCtx, remoteGuides);
+        }
+        // Write given remote guides into the given guides directory path.
+        const writeGuideDirPromises = remoteGuides.map(async (guide)=>{
+            const guideDirPath = _nodepath.resolve(indexDirCtx.abspath, guide.key);
+            const guideDirCtx = {
+                type: "guide",
+                key: guide.key,
+                abspath: guideDirPath,
+                exists: indexDirCtx.exists ? await (0, _helpers.isGuideDir)(guideDirPath) : false
+            };
+            return writeGuideDirFromData(guideDirCtx, guide);
+        });
+        await Promise.all(writeGuideDirPromises);
+    } catch (error) {
+        console.log(error);
+        // In case of any error, wipe the index directory that is likely in a bad
+        // state then restore the backup if one existed before.
+        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);
+    }
+};