🍕 Always run PostCSS over Vue <style> blocks in clay compile scripts

CLAYCLI_COMPILE_SCRIPTS_SKIP_STYLE_POSTCSS was treating two unrelated
concerns as a single switch:

  1. The PostCSS plugin chain (cssImport → autoprefixer → mixins →
     nested → simple-vars), needed for every <style> block to flatten
     `&-foo` nesting and resolve simple variables.
  2. The sass/scss preprocessor (node-sass → dart-sass), introduced to
     dodge node-sass native-binding failures in some Docker stages.

When the env var was set, the chain in (1) was disabled too, so kiln
plugin <style> blocks reached the browser as nested CSS no UA can
parse. Modals built from local .vue files (article-picker, agora,
mediaplay-picker, …) consequently rendered unstyled — even on sites
served by the existing Browserify pipeline.

This commit decouples them: the PostCSS chain now always runs; the env
var only swaps in the dart-sass preprocessor.

Plugins are resolved from the host project's node_modules first so the
chain runs against the host's PostCSS major. If the host has no PostCSS
installed at all, claycli's bundled copies are used instead. Mixing the
two trees is avoided — picking individual plugins across versions
triggers "PostCSS plugin X requires PostCSS Y" failures because each
plugin's `Symbol.for('postcss')` is anchored to whichever postcss it
was installed alongside. Plugins absent from the chosen tree are
dropped silently (postcss-mixins is a transitive of vueify only and may
legitimately be absent from a host).

Verified locally on nymag/sites: clay compile scripts emits a 65 KB
_kiln-plugins.css with zero raw `&-` selectors (was 56 KB / 180 nested
matches), and the agora / article-picker modals render correctly.

Companion to the equivalent fix in lib/cmd/vite/plugins/vue2.js so the
two pipelines produce equivalent output for kiln plugin SFCs.

Made-with: Cursor

Author: jjpaulino

lib/cmd/compile/scripts.js

@@ -23,11 +23,10 @@ const _ = require('lodash'),
   vueify = require('@nymag/vueify'),
   uglifyify = require('uglifyify'),
   extractCSS = require('@nymag/vueify/plugins/extract-css'),
-  autoprefixer = require('autoprefixer'),
-  cssImport = require('postcss-import'),
-  mixins = require('postcss-mixins'),
-  nested = require('postcss-nested'),
-  simpleVars  = require('postcss-simple-vars'),
+  // PostCSS plugins applied to Vue <style> blocks are resolved lazily from
+  // the host project's node_modules in buildVuePostcssChain() so the chain
+  // runs against the host's PostCSS major. Keeping them off the top-level
+  // require list avoids pinning claycli's bundled (PostCSS 8) copies.
   reporters = require('../../reporters'),
   helpers = require('../../compilation-helpers'),
   // globbing patterns
@@ -66,6 +65,69 @@ const _ = require('lodash'),
   },
   temporaryIDs = {};
 
+/**
+ * Resolve a PostCSS plugin from a specific node_modules tree.
+ * Returns the plugin's module export, or null if it isn't installed there.
+ *
+ * @param {string}   name   npm package name
+ * @param {string[]} paths  resolution roots (passed to require.resolve)
+ * @returns {*}
+ */
+function resolvePostcssPlugin(name, paths) {
+  try {
+    return require(require.resolve(name, { paths }));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Build the PostCSS plugin chain applied to every Vue <style> block.
+ *
+ * Mirrors the legacy vueify chain (cssImport → autoprefixer → mixins →
+ * nested → simple-vars).
+ *
+ * Resolution strategy: prefer the host project's node_modules so the chain
+ * runs against the host's PostCSS major. If the host has no PostCSS at all,
+ * fall back to claycli's bundled copies for the whole chain. We never mix
+ * the two — picking individual plugins across versions causes runtime
+ * "PostCSS plugin X requires PostCSS Y" failures because each plugin's
+ * `Symbol.for('postcss')` namespace is anchored to whichever postcss it
+ * was installed alongside.
+ *
+ * Plugins that aren't installed in the chosen tree are dropped silently —
+ * the chain still runs whatever resolved, matching the legacy best-effort
+ * behaviour. (postcss-mixins, for example, is a transitive of @nymag/vueify
+ * only and may legitimately be absent from a host project.)
+ *
+ * @returns {Array}
+ */
+function buildVuePostcssChain() {
+  const hostPaths = [process.cwd()];
+  const useHost = !!resolvePostcssPlugin('postcss', hostPaths);
+  const paths = useHost ? hostPaths : undefined; // undefined → claycli's own resolver
+  const specs = [
+    { name: 'postcss-import',      args: () => [] },
+    { name: 'autoprefixer',        args: () => [helpers.getConfigFileOrBrowsersList('autoprefixerOptions')] },
+    { name: 'postcss-mixins',      args: () => [] },
+    { name: 'postcss-nested',      args: () => [] },
+    { name: 'postcss-simple-vars', args: () => [] },
+  ];
+
+  return specs.reduce((chain, { name, args }) => {
+    let plugin;
+
+    if (paths) {
+      plugin = resolvePostcssPlugin(name, paths);
+    } else {
+      try { plugin = require(name); } catch (_) { plugin = null; }
+    }
+
+    if (typeof plugin === 'function') chain.push(plugin(...args()));
+    return chain;
+  }, []);
+}
+
 /**
  * copy kiln js if it has changed
  * note: kiln compiles its own js, so this just copies it to the public folder
@@ -377,18 +439,26 @@ function buildScripts(entries, options = {}) {
     }
   }
 
-  if (!skipVueStylePostcss) {
-    vueifyTransformOptions.postcss = [
-      cssImport(),
-      autoprefixer(helpers.getConfigFileOrBrowsersList('autoprefixerOptions')),
-      mixins(),
-      nested(),
-      simpleVars()
-    ];
-  } else {
-    // Vueify's default sass/scss compiler requires node-sass.
-    // During staged rollout we intentionally skip this postcss path and
-    // compile sass/scss with dart-sass to avoid node-sass runtime failures.
+  // PostCSS chain over Vue <style> blocks must always run. Source like
+  // `.foo { &-bar { … } }` reaches the browser as a nested rule no UA can
+  // parse without postcss-nested, so kiln plugin modals (article-picker,
+  // agora, mediaplay-picker, …) render unstyled if this is skipped.
+  //
+  // Plugins are resolved from the host project's node_modules first so the
+  // chain runs against the host's PostCSS major (e.g. PostCSS 7 in
+  // nymag/sites, where claycli's bundled autoprefixer@10 would otherwise
+  // throw "autoprefixer requires PostCSS 8" at compile time). If a host
+  // copy isn't present we fall back to claycli's bundled require — that
+  // covers projects already on PostCSS 8 with no host-side install.
+  // Anything that fails to resolve in both locations is dropped silently.
+  vueifyTransformOptions.postcss = buildVuePostcssChain();
+
+  // CLAYCLI_COMPILE_SCRIPTS_SKIP_STYLE_POSTCSS controls the sass/scss
+  // preprocessor only. Vueify's default uses node-sass (native binding,
+  // unbuildable in some Docker stages); during staged rollout we swap in
+  // dart-sass to avoid that runtime failure. The env var name is kept for
+  // backwards compatibility but no longer affects the PostCSS chain above.
+  if (skipVueStylePostcss) {
     vueifyTransformOptions.customCompilers = {
       sass: compileSassWithDartSass,
       scss: compileSassWithDartSass