feat(targets): Add target for editing UPWARD definitions (DRAFT)

packages/pwa-buildpack/lib/BuildBus/declare-base.js

@@ -138,7 +138,47 @@ module.exports = targets => {
          * @param {Object<(string, boolean)>} featureFlags
          * @memberof BuiltinTargets
          */
-        specialFeatures: new targets.types.Sync(['special'])
+        specialFeatures: new targets.types.Sync(['special']),
+
+        /**
+         * @callback transformUpwardIntercept
+         * @param {object} Parsed UPWARD definition object.
+         * @returns {Promise} - Interceptors do not need to return.
+         */
+
+        /**
+         * Exposes the fully merged UPWARD definition for fine tuning. The
+         * UpwardIncludePlugin does a simple shallow merge of the upward.yml
+         * files in every package which sets the `upward: true` flag in the
+         * `specialFeatures` object. After that is complete,
+         * UpwardIncludePlugin calls this target with the parsed and merged
+         * definition.
+         *
+         * @example <caption>Send empty responses in maintenance mode.</caption>
+         * targets.of('@magento/pwa-buildpack').transformUpward.tap(def => {
+         *   const guardMaintenanceMode = (prop, inline) => {
+         *     def[prop] = {
+         *       when: [
+         *         {
+         *           matches: 'env.MAINTENANCE_MODE',
+         *           pattern: '.',
+         *           use: { inline }
+         *         }
+         *       ],
+         *       default: def[prop]
+         *     }
+         *   }
+         *
+         *   guardMaintenanceMode('status', 503);
+         *   guardMaintenanceMode('body', '')
+         * })
+         *
+         *
+         * @type {tapable.AsyncSeriesHook}
+         * @param {transformUpwardIntercept} interceptor
+         * @memberof BuiltinTargets
+         */
+        transformUpward: new targets.types.AsyncSeries(['definitions'])
     };
 
     /**

packages/pwa-buildpack/lib/WebpackTools/configureWebpack/getClientConfig.js

@@ -33,7 +33,8 @@ async function getClientConfig(opts) {
         vendor,
         projectConfig,
         stats,
-        resolver
+        resolver,
+        bus
     } = opts;
 
     let vendorTest = '[\\/]node_modules[\\/]';
@@ -82,6 +83,7 @@ async function getClientConfig(opts) {
             }),
             new webpack.EnvironmentPlugin(projectConfig.env),
             new UpwardIncludePlugin({
+                bus,
                 upwardDirs: [...hasFlag('upward'), context]
             }),
             new WebpackAssetsManifest({

packages/pwa-buildpack/lib/WebpackTools/plugins/UpwardIncludePlugin.js

@@ -10,7 +10,8 @@ const jsYaml = require('js-yaml');
  * autodetects file assets relied on by those configurations
  */
 class UpwardIncludePlugin {
-    constructor({ upwardDirs }) {
+    constructor({ bus, upwardDirs }) {
+        this.bus = bus;
         this.upwardDirs = upwardDirs;
         this.definition = {};
         debug('created with dirs: %s', upwardDirs);
@@ -33,7 +34,12 @@ class UpwardIncludePlugin {
                 context,
                 from: './upward.yml',
                 to: './upward.yml',
-                transform: () => jsYaml.safeDump(this.definition)
+                transform: async () => {
+                    await this.bus
+                        .getTargetsOf('@magento/pwa-buildpack')
+                        .transformUpward.promise(this.definition);
+                    return jsYaml.safeDump(this.definition);
+                }
             }
         };
         this.dirs = new Set([...this.upwardDirs, context]);