ghost 5.115.0 → 5.116.0

package/core/server/lib/package-json/package-json.js

@@ -0,0 +1,160 @@
+/*
+ * # Package Utils
+ *
+ * Ghost has support for several different types of sub-packages:
+ * - Themes: have always been packages, but we're going to lean more heavily on npm & package.json in future
+ * - Adapters: replace fundamental pieces like storage, will become npm modules
+ *
+ * These utils facilitate loading, reading, managing etc, packages from the file system.
+ *
+ */
+const _ = require('lodash');
+const fs = require('fs-extra');
+const join = require('path').join;
+const errors = require('@tryghost/errors');
+const parse = require('./parse');
+
+const notAPackageRegex = /^\.|_messages|README.md|node_modules|bower_components/i;
+const packageJSONPath = 'package.json';
+
+/**
+ * @typedef {object} PackageList
+ * @typedef {object} Package
+ */
+
+/**
+ * Recursively read directory and find the packages in it
+ *
+ * @param {string} absolutePath
+ * @param {string} packageName
+ * @returns {Promise<Package>}
+ */
+async function processPackage(absolutePath, packageName) {
+    const pkg = {
+        name: packageName,
+        path: absolutePath
+    };
+
+    try {
+        const packageJSON = await parse(join(absolutePath, packageJSONPath));
+        pkg['package.json'] = packageJSON;
+    } catch (err) {
+        // ignore invalid package.json for now,
+        // because Ghost does not rely/use them at the moment
+        // in the future, this .catch() will need to be removed,
+        // so that error is thrown on invalid json syntax
+        pkg['package.json'] = null;
+    }
+
+    return pkg;
+}
+
+/**
+ * ### Filter Packages
+ * Normalizes packages read by readPackages so that the themes module can use them.
+ * Iterates over each package and return an array of objects which are simplified representations of the package
+ * with 3 properties:
+ *
+ * @typedef {object} SimplePackage
+ * @prop {string} name    - the package name
+ * @prop {object|boolean} package - contents of the package.json or false if there isn't one
+ * @prop {boolean} active  - set to true if this package is active
+ *
+ * This data structure is used for listings of packages provided over the API and as such
+ * deliberately combines multiple sources of information in order to be efficient.
+ *
+ * TODO: simplify the package.json representation to contain only fields we use
+ *
+ * @param   {PackageList}       packages    object made up of packages keyed by name as returned by readPackages
+ * @param   {array|string}      [active]    optional set of names of packages that are active
+ * @returns {Array<SimplePackage>}          array of objects with useful info about themes
+ */
+function filter(packages, active) {
+    // turn active into an array if it isn't one, so this function can deal with lists and one-offs
+    if (!Array.isArray(active)) {
+        active = [active];
+    }
+
+    return _.reduce(packages, function (result, pkg, key) {
+        let item = {};
+        if (!key.match(notAPackageRegex)) {
+            item = {
+                name: key,
+                package: pkg['package.json'] || false,
+                active: _.indexOf(active, key) !== -1
+            };
+
+            result.push(item);
+        }
+
+        return result;
+    }, []);
+}
+
+/**
+ * @param {string} packagePath
+ * @param {string} packageName
+ * @returns {Promise<Package>}
+ */
+async function readPackage(packagePath, packageName) {
+    const absolutePath = join(packagePath, packageName);
+
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isDirectory()) {
+            return {};
+        }
+
+        const pkg = await processPackage(absolutePath, packageName);
+        const res = {};
+        res[packageName] = pkg;
+        return res;
+    } catch (err) {
+        return Promise.reject(new errors.NotFoundError({
+            message: 'Package not found',
+            err: err,
+            help: 'path: ' + packagePath,
+            context: 'name: ' + packageName
+        }));
+    }
+}
+
+/**
+ * @param {string} packagePath
+ * @returns {Promise<PackageList>}
+ */
+async function readPackages(packagePath) {
+    const files = await fs.promises.readdir(packagePath, {withFileTypes: true});
+    const packages = await Promise.all(files.map(async (file) => {
+        // Filter out things which are not packages by regex
+        if (file.name.match(notAPackageRegex)) {
+            return false;
+        }
+
+        if (file.isSymbolicLink()) {
+            try {
+                const packageFileOrig = await fs.stat(join(packagePath, file.name));
+                return packageFileOrig.isDirectory();
+            } catch (err) {
+                // if there's an error reading the symlink, we should just return false
+                return false;
+            }
+        }
+
+        // Check the remaining items to ensure they are a directory
+        return file.isDirectory();
+    }))
+        .then(results => files.filter((_v, index) => results[index]))
+        .then(packageFiles => Promise.all(packageFiles.map((packageFile) => {
+            const absolutePath = join(packagePath, packageFile.name);
+            return processPackage(absolutePath, packageFile.name);
+        })));
+
+    return _.keyBy(packages, 'name');
+}
+
+module.exports = {
+    filter,
+    readPackage,
+    readPackages
+};

package/core/server/lib/package-json/parse.js

@@ -0,0 +1,57 @@
+const fs = require('fs-extra');
+const errors = require('@tryghost/errors');
+const tpl = require('@tryghost/tpl');
+
+const messages = {
+    couldNotReadPackage: 'Could not read package.json file',
+    nameOrVersionMissing: '"name" or "version" is missing from theme package.json file.',
+    willBeRequired: 'This will be required in future. Please see {url}',
+    themeFileIsMalformed: 'Theme package.json file is malformed'
+};
+
+/**
+ * Parse package.json and validate it has
+ * all the required fields
+ *
+ * @param {string} path
+ * @returns {Promise<object>}
+ */
+async function parse(path) {
+    let source;
+    let json;
+
+    try {
+        source = await fs.readFile(path, {encoding: 'utf8'});
+    } catch (readError) {
+        throw new errors.IncorrectUsageError({
+            message: tpl(messages.couldNotReadPackage),
+            context: path,
+            err: readError
+        });
+    }
+
+    try {
+        json = JSON.parse(source);
+    } catch (parseError) {
+        throw new errors.IncorrectUsageError({
+            message: tpl(messages.themeFileIsMalformed),
+            context: path,
+            err: parseError,
+            help: tpl(messages.willBeRequired, {url: 'https://ghost.org/docs/themes/'})
+        });
+    }
+
+    const hasRequiredKeys = json.name && json.version;
+
+    if (!hasRequiredKeys) {
+        throw new errors.IncorrectUsageError({
+            message: tpl(messages.nameOrVersionMissing),
+            context: path,
+            help: tpl(messages.willBeRequired, {url: 'https://ghost.org/docs/themes/'})
+        });
+    }
+
+    return json;
+}
+
+module.exports = parse;

package/core/server/models/base/plugins/actions.js

@@ -3,9 +3,20 @@ const errors = require('@tryghost/errors');
 const logging = require('@tryghost/logging');
 
 /**
+ * This plugin is used to add actions to the database. It backs the "audit log" feature we have in Ghost.
+ *
+ * The functions here are triggered by the `onCreated`, `onUpdated`, `onDeleted` functions in the `events`
+ * plugin, with some extra ones for niche other events.
+ *
  * @param {import('bookshelf')} Bookshelf
  */
 module.exports = function (Bookshelf) {
+    /**
+     * Insert an action into the database
+     *
+     * @param {Object} data - The data to insert
+     * @param {Object} options - The options object
+     */
     const insertAction = (data, options) => {
         // CASE: model does not support action for target event
         if (!data) {
@@ -39,7 +50,13 @@ module.exports = function (Bookshelf) {
         }
     };
 
-    // We need this addAction accessible from the static model and instances
+    /**
+     * Add an action to the database
+     *
+     * @param {import('bookshelf').Model} model - The model to add the action to
+     * @param {string} event - The event that triggered the action
+     * @param {Object} options - The options object
+     */
     const addAction = (model, event, options) => {
         if (!model.wasChanged()) {
             return;
@@ -58,11 +75,14 @@ module.exports = function (Bookshelf) {
         /**
          * Constructs data to be stored in the database with info
          * on particular actions
+         *
+         * @param {string} event - The event that triggered the action
+         * @param {Object} options - The options object
+         * @returns {Object} The data to be stored in the database
          */
         getAction(event, options) {
+            // Ignore internal updates (`options.context.internal`) for now
             const actor = this.getActor(options);
-
-            // @NOTE: we ignore internal updates (`options.context.internal`) for now
             if (!actor) {
                 return;
             }
@@ -71,12 +91,7 @@ module.exports = function (Bookshelf) {
                 return;
             }
 
-            let resourceType = this.actionsResourceType;
-
-            if (typeof resourceType === 'function') {
-                resourceType = resourceType.bind(this)();
-            }
-
+            const resourceType = this.actionsResourceType;
             if (!resourceType) {
                 return;
             }
@@ -85,12 +100,14 @@ module.exports = function (Bookshelf) {
                 action_name: options.actionName
             };
 
+            // Used to attach extra content to the action (ie. the key + group for settings changes)
             if (this.actionsExtraContext && Array.isArray(this.actionsExtraContext)) {
                 for (const c of this.actionsExtraContext) {
                     context[c] = this.get(c) || this.previous(c);
                 }
             }
 
+            // Attach the primary name to the action (ie. the title or name of the model)
             if (event === 'deleted') {
                 context.primary_name = (this.previous('title') || this.previous('name'));
             } else if (['added', 'edited'].includes(event)) {
@@ -112,21 +129,17 @@ module.exports = function (Bookshelf) {
             return data;
         },
 
-        /**
-         * @NOTE:
-         *
-         * We add actions step by step and define how they should look like.
-         * Each post update triggers a couple of events, which we don't want to add actions for.
-         *
-         * e.g. transform post to page triggers a handful of events including `post.deleted` and `page.added`
-         *
-         * We protect adding too many and uncontrolled events.
-         *
-         * We could embed adding actions more nicely in the future e.g. plugin.
-         */
         addAction
     }, {
         addAction,
+
+        /**
+         * Add actions for bulk actions
+         *
+         * @param {string} event - The event that triggered the action
+         * @param {number[]} ids - The ids of the models that were affected
+         * @param {Object} options - The options object
+         */
         async addActions(event, ids, options) {
             if (ids.length === 1) {
                 // We want to store an event for a single model in the actions table
@@ -141,27 +154,27 @@ module.exports = function (Bookshelf) {
         },
 
         /**
-         * Constructs data to be stored in the database with info
-         * on particular actions
+         * Constructs data for bulk actions to be stored in the database
+         *
+         * @param {string} event - The event that triggered the action
+         * @param {number} count - The number of models that were affected
+         * @param {Object} options - The options object
+         * @returns {Object} The data to be stored in the database
          */
         getBulkAction(event, count, options) {
+            // Ignore internal updates (`options.context.internal`) for now
             const actor = this.prototype.getActor(options);
-
-            // @NOTE: we ignore internal updates (`options.context.internal`) for now
             if (!actor) {
                 return;
             }
 
+            // Models can opt-in to their CRUD actions being collected (we do this so we don't
+            // log every single action)
             if (!this.prototype.actionsCollectCRUD) {
                 return;
             }
 
-            let resourceType = this.prototype.actionsResourceType;
-
-            if (typeof resourceType === 'function') {
-                resourceType = resourceType.bind(this)();
-            }
-
+            const resourceType = this.prototype.actionsResourceType;
             if (!resourceType) {
                 return;
             }

package/core/server/models/base/plugins/generate-slug.js

@@ -39,6 +39,12 @@ module.exports = function (Bookshelf) {
                         return slugToFind;
                     }
 
+                    if (options.modelId) {
+                        if (found.id === options.modelId) {
+                            return slugToFind;
+                        }
+                    }
+
                     slugTryCount += 1;
 
                     // If we shortened, go back to the full version and try again

package/core/server/notify.js

@@ -51,7 +51,7 @@ async function notify(type, error = null) {
     // CASE: use bootstrap socket to communicate with CLI for systemd
     let socketAddress = config.get('bootstrap-socket');
     if (socketAddress) {
-        const bootstrapSocket = require('@tryghost/bootstrap-socket');
+        const bootstrapSocket = require('./lib/bootstrap-socket');
         return bootstrapSocket.connectAndSend(socketAddress, message);
     }
 

package/core/server/services/activitypub/ActivityPubService.ts

@@ -1,6 +1,6 @@
 import ObjectID from 'bson-objectid';
 import {Knex} from 'knex';
-import {IdentityTokenService} from '@tryghost/identity-token-service';
+import {IdentityTokenService} from '../identity-tokens/IdentityTokenService';
 import fetch from 'node-fetch';
 
 type ExpectedWebhook = {

package/core/server/services/adapter-manager/AdapterManager.js

@@ -0,0 +1,161 @@
+const path = require('path');
+const errors = require('@tryghost/errors');
+
+/**
+ * @typedef { function(new: Adapter, object) } AdapterConstructor
+ */
+
+/**
+ * @typedef {object} Adapter
+ * @prop {string[]} requiredFns
+ */
+
+module.exports = class AdapterManager {
+    /**
+     * @param {object} config
+     * @param {string[]} config.pathsToAdapters The paths to check, e.g. ['content/adapters', 'core/server/adapters']
+     * @param {(path: string) => AdapterConstructor} config.loadAdapterFromPath A function to load adapters, e.g. global.require
+     */
+    constructor({pathsToAdapters, loadAdapterFromPath}) {
+        /**
+         * @private
+         * @type {Object.<string, AdapterConstructor>}
+         */
+        this.baseClasses = {};
+
+        /**
+         * @private
+         * @type {Object.<string, Object.<string, Adapter>>}
+         */
+        this.instanceCache = {};
+
+        /**
+         * @private
+         * @type {string[]}
+         */
+        this.pathsToAdapters = pathsToAdapters;
+
+        /**
+         * @private
+         * @type {(path: string) => AdapterConstructor}
+         */
+        this.loadAdapterFromPath = loadAdapterFromPath;
+    }
+
+    /**
+     * Register an adapter type and the corresponding base class. Must be called before requesting adapters of that type
+     *
+     * @param {string} type The name for the type of adapter
+     * @param {AdapterConstructor} BaseClass The class from which all adapters of this type must extend
+     */
+    registerAdapter(type, BaseClass) {
+        this.instanceCache[type] = {};
+        this.baseClasses[type] = BaseClass;
+    }
+
+    /**
+     * Force recreation of all instances instead of reusing cached instances. Use when editing config file during tests.
+     */
+    clearInstanceCache() {
+        for (const key of Object.keys(this.instanceCache)) {
+            this.instanceCache[key] = {};
+        }
+    }
+
+    /**
+     * getAdapter
+     *
+     * @param {string} adapterName The name of the type of adapter, e.g. "storage" or "scheduling", optionally including the feature, e.g. "storage:files"
+     * @param {string} adapterClassName The active adapter instance class name e.g. "LocalFileStorage"
+     * @param {object} [config] The config the adapter could be instantiated with
+     *
+     * @returns {Adapter} The resolved and instantiated adapter
+     */
+    getAdapter(adapterName, adapterClassName, config) {
+        if (!adapterName || !adapterClassName) {
+            throw new errors.IncorrectUsageError({
+                message: 'getAdapter must be called with a adapterName and a adapterClassName.'
+            });
+        }
+
+        let adapterType;
+        if (adapterName.includes(':')) {
+            [adapterType] = adapterName.split(':');
+        } else {
+            adapterType = adapterName;
+        }
+
+        const adapterCache = this.instanceCache[adapterType];
+
+        if (!adapterCache) {
+            throw new errors.NotFoundError({
+                message: `Unknown adapter type ${adapterType}. Please register adapter.`
+            });
+        }
+
+        // @NOTE: example cache key value 'email:newsletters:custom-newsletter-adapter'
+        const adapterCacheKey = `${adapterName}:${adapterClassName}`;
+        if (adapterCache[adapterCacheKey]) {
+            return adapterCache[adapterCacheKey];
+        }
+
+        /** @type AdapterConstructor */
+        let Adapter;
+        for (const pathToAdapters of this.pathsToAdapters) {
+            const pathToAdapter = path.join(pathToAdapters, adapterType, adapterClassName);
+            try {
+                Adapter = this.loadAdapterFromPath(pathToAdapter);
+                if (Adapter) {
+                    break;
+                }
+            } catch (err) {
+                // Catch runtime errors
+                if (err.code !== 'MODULE_NOT_FOUND') {
+                    throw new errors.IncorrectUsageError({err});
+                }
+
+                // Catch missing dependencies BUT NOT missing adapter
+                if (!err.message.includes(pathToAdapter)) {
+                    throw new errors.IncorrectUsageError({
+                        message: `You are missing dependencies in your adapter ${pathToAdapter}`,
+                        err
+                    });
+                }
+            }
+        }
+
+        if (!Adapter) {
+            throw new errors.IncorrectUsageError({
+                message: `Unable to find ${adapterType} adapter ${adapterClassName} in ${this.pathsToAdapters}.`
+            });
+        }
+
+        const adapter = new Adapter(config);
+
+        if (!(adapter instanceof this.baseClasses[adapterType])) {
+            if (Object.getPrototypeOf(Adapter).name !== this.baseClasses[adapterType].name) {
+                throw new errors.IncorrectUsageError({
+                    message: `${adapterType} adapter ${adapterClassName} does not inherit from the base class.`
+                });
+            }
+        }
+
+        if (!adapter.requiredFns) {
+            throw new errors.IncorrectUsageError({
+                message: `${adapterType} adapter ${adapterClassName} does not have the requiredFns.`
+            });
+        }
+
+        for (const requiredFn of adapter.requiredFns) {
+            if (typeof adapter[requiredFn] !== 'function') {
+                throw new errors.IncorrectUsageError({
+                    message: `${adapterType} adapter ${adapterClassName} is missing the ${requiredFn} method.`
+                });
+            }
+        }
+
+        adapterCache[adapterCacheKey] = adapter;
+
+        return adapter;
+    }
+};

package/core/server/services/adapter-manager/index.js

@@ -1,4 +1,4 @@
-const AdapterManager = require('@tryghost/adapter-manager');
+const AdapterManager = require('./AdapterManager');
 const getAdapterServiceConfig = require('./config');
 const resolveAdapterOptions = require('./options-resolver');
 const config = require('../../../shared/config');

package/core/server/services/announcement-bar-service/AnnouncementBarSettings.js

@@ -0,0 +1,54 @@
+const AnnouncementVisibilityValues = require('./AnnouncementVisibilityValues');
+
+class AnnouncementBarSettings {
+    #getAnnouncementSettings;
+
+    static VisibilityValues = AnnouncementVisibilityValues;
+
+    /**
+     *
+     * @param {Object} deps
+     * @param {() => {announcement: string, announcement_visibility: string[], announcement_background: string}} deps.getAnnouncementSettings
+     */
+    constructor(deps) {
+        this.#getAnnouncementSettings = deps.getAnnouncementSettings;
+    }
+
+    /**
+     * @param {Object} [member]
+     * @param {string} member.status
+     * @returns {{announcement: string, announcement_background: string}}
+     */
+    getAnnouncementSettings(member) {
+        let announcement = undefined;
+
+        // NOTE: combination of 'free_members' & 'paid_members' makes just a 'members' filter
+        const announcementSettings = this.#getAnnouncementSettings();
+
+        if (announcementSettings.announcement) {
+            const visibilities = announcementSettings.announcement_visibility;
+            const announcementContent = announcementSettings.announcement;
+
+            if (visibilities.length === 0) {
+                announcement = undefined;
+            } else {
+                if (visibilities.includes(AnnouncementVisibilityValues.VISITORS) && !member) {
+                    announcement = announcementContent;
+                } else if (visibilities.includes(AnnouncementVisibilityValues.FREE_MEMBERS) && (member?.status === 'free')) {
+                    announcement = announcementContent;
+                } else if (visibilities.includes(AnnouncementVisibilityValues.PAID_MEMBERS) && (member && member.status !== 'free')) {
+                    announcement = announcementContent;
+                }
+            }
+        }
+
+        if (announcement !== undefined) {
+            return {
+                announcement,
+                announcement_background: announcementSettings.announcement_background
+            };
+        }
+    }
+}
+
+module.exports = AnnouncementBarSettings;

package/core/server/services/announcement-bar-service/AnnouncementVisibilityValues.js

@@ -0,0 +1,11 @@
+// Available visibilities:
+// 'visitors' - anonymous visitors
+// 'free_members' - free members
+// 'paid_members' - paid members (aka non-free members)
+class AnnouncementVisibilityValues {
+    static VISITORS = 'visitors';
+    static FREE_MEMBERS = 'free_members';
+    static PAID_MEMBERS = 'paid_members';
+}
+
+module.exports = AnnouncementVisibilityValues;

package/core/server/services/announcement-bar-service/index.js

@@ -1,5 +1,5 @@
 const settingsCache = require('../../../shared/settings-cache');
-const AnnouncementBarSettings = require('@tryghost/announcement-bar-settings');
+const AnnouncementBarSettings = require('./AnnouncementBarSettings');
 
 const announcementBarService = new AnnouncementBarSettings({
     getAnnouncementSettings: () => ({