ghost 6.63.0 → 6.65.0

package/bin/create-migration.js

@@ -22,6 +22,10 @@ module.exports = /**/;
 
 const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
+/**
+ * @param {unknown} slug
+ * @returns {slug is string}
+ */
 function isValidSlug(slug) {
   return typeof slug === 'string' && SLUG_PATTERN.test(slug);
 }
@@ -29,6 +33,9 @@ function isValidSlug(slug) {
 /**
  * Resolves the most recent stable tag (e.g. v6.34.0) from git.
  * Excludes prerelease tags so the answer reflects what's actually shipped.
+ *
+ * @param {string} cwd
+ * @returns {string}
  */
 function readLastPublishedVersion(cwd) {
   const tag = execSync(
@@ -38,6 +45,10 @@ function readLastPublishedVersion(cwd) {
   return tag.replace(/^v/, '');
 }
 
+/**
+ * @param {string} version
+ * @returns {string}
+ */
 function minorOf(version) {
   return `${semver.major(version)}.${semver.minor(version)}`;
 }
@@ -54,6 +65,10 @@ function minorOf(version) {
  *   package 6.34.1-rc.0 → folder 6.35   (needs promote)
  *   package 6.35.0-rc.0 → folder 6.35   (already promoted)
  *   package 6.34.0      → folder 6.35   (needs promote, e.g. fresh checkout)
+ *
+ * @param {string} packageVersion
+ * @param {string} lastPublishedVersion
+ * @returns {string}
  */
 function getTargetMigrationFolder(packageVersion, lastPublishedVersion) {
   const packageMinor = minorOf(packageVersion);

package/bin/lib/duplicate-deps.js

@@ -0,0 +1,204 @@
+"use strict";
+// Finds packages loaded twice in one process: once from a custom adapter's own
+// `node_modules` and once from Ghost's.
+//
+// An adapter is installed as a self-contained directory with its own dependency
+// tree (Ghost Pro deploys them to `/home/ghost/adapters/<type>/<Name>`). Whatever
+// it doesn't install itself resolves by walking up to Ghost's `node_modules`, so
+// a package it *does* install becomes a second module instance - which breaks
+// `instanceof` against a base class (hence the name-based fallbacks in
+// `adapter-manager.ts` and `bin/validate-adapters.ts`) and splits module-level
+// state, as `@tryghost/metrics` would with no `globalThis` guard to save it.
+//
+// @NOTE: `collectLoadedFiles` unions two sources because neither contains the
+// other. `require.cache` holds no ESM file, neither an ESM adapter's entry point
+// nor anything it `import`s - though a CommonJS dependency of one does still go
+// through the cache, so the gap is ESM files specifically. The inspector reports
+// every script V8 parsed, ESM included, but `.json` and native `.node` modules
+// aren't scripts and only the cache lists them. The cache is also the fallback
+// when the inspector is unavailable.
+//
+// @NOTE: this is for the installed tree built into an image, not a local
+// checkout. Ghost's copy of a `workspace:*` dependency - every adapter base class
+// among them - resolves through a symlink to `packages/<name>`, outside any
+// `node_modules`, leaving an adapter's copy with nothing to be compared against.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectLoadedFiles = collectLoadedFiles;
+exports.parsePackageFromPath = parsePackageFromPath;
+exports.checkDuplicateDependencies = checkDuplicateDependencies;
+exports.formatDuplicateReport = formatDuplicateReport;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_inspector_1 = __importDefault(require("node:inspector"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const NODE_MODULES = 'node_modules';
+/**
+ * The files V8 has parsed in this process, whatever their module format.
+ *
+ * Enabling the `Debugger` domain replays a `scriptParsed` event for every script
+ * already parsed, synchronously, so this can run after the adapters have and
+ * there is nothing to await. Empty when the inspector is unavailable, e.g. a Node
+ * built `--without-inspector`.
+ */
+function parsedScriptFiles() {
+    let session;
+    try {
+        session = new node_inspector_1.default.Session();
+        session.connect();
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    session.on('Debugger.scriptParsed', ({ params }) => {
+        // Nothing with no file behind it - `node:` internals, `eval`, `data:` URLs -
+        // can belong to a package.
+        if (!params.url.startsWith('file://')) {
+            return;
+        }
+        try {
+            files.push((0, node_url_1.fileURLToPath)(params.url));
+        }
+        catch {
+            // Nor anything Node won't convert back to a path.
+        }
+    });
+    session.post('Debugger.enable');
+    session.post('Debugger.disable');
+    session.disconnect();
+    return files;
+}
+/** Every file this process has loaded, from both of the sources above. */
+function collectLoadedFiles(cjsCachedFiles) {
+    return [...new Set([...cjsCachedFiles, ...parsedScriptFiles()])];
+}
+function realpathOrNull(target) {
+    try {
+        return node_fs_1.default.realpathSync(target);
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `filePath` sits inside `directory`. Both are expected to be realpaths. */
+function isInside(filePath, directory) {
+    const relative = node_path_1.default.relative(directory, filePath);
+    // Match the first segment exactly, so a name that merely begins with dots
+    // isn't taken for traversal the way startsWith('..') would take it.
+    const [firstSegment] = relative.split(node_path_1.default.sep);
+    return relative !== '' && firstSegment !== '..' && !node_path_1.default.isAbsolute(relative);
+}
+/** The version a package declares, or `unknown` - better reported than dropped. */
+function readVersion(packagePath) {
+    try {
+        const { version } = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(packagePath, 'package.json'), 'utf8'));
+        return typeof version === 'string' ? version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Attribute a loaded file to the package that physically contains it: whatever
+ * the *last* `node_modules` segment of its path names. That holds for any
+ * installer's layout, npm's flat `node_modules/<name>` and pnpm's
+ * `.pnpm/<name>@<version>/node_modules/<name>` alike. `null` when the file is in
+ * no package: Ghost's own source, or an adapter's own `index.js`.
+ */
+function parsePackageFromPath(filePath) {
+    const segments = filePath.split(node_path_1.default.sep);
+    const start = segments.lastIndexOf(NODE_MODULES) + 1;
+    const first = segments[start];
+    // A dot-prefixed entry is an installer's own directory - pnpm's store, `.bin`,
+    // a cache - and npm forbids a package name from looking like one.
+    if (start === 0 || !first || first.startsWith('.')) {
+        return null;
+    }
+    // Scoped packages take two segments: `@tryghost/logging`.
+    const end = start + (first.startsWith('@') ? 2 : 1);
+    if (!segments[end - 1]) {
+        return null;
+    }
+    return {
+        name: segments.slice(start, end).join('/'),
+        path: segments.slice(0, end).join(node_path_1.default.sep),
+    };
+}
+/**
+ * Find packages loaded from both an adapter's dependency tree and Ghost's own.
+ *
+ * Adapters are checked first: `content/adapters` lives inside the Ghost
+ * installation, so the two sides are not mutually exclusive.
+ */
+function checkDuplicateDependencies({ cachedFiles, adapterRoots, ghostNodeModulesRoots, mustBeSingleCopy, }) {
+    // Compare resolved paths on both sides, never specifiers: `require.cache`
+    // reports realpaths, and pnpm reaches these roots through symlinks.
+    const realAdapterRoots = adapterRoots.map(realpathOrNull).filter((root) => root !== null);
+    const realGhostRoots = ghostNodeModulesRoots.map(realpathOrNull).filter((root) => root !== null);
+    const adapterPackages = new Map();
+    const ghostPackages = new Map();
+    for (const cachedFile of cachedFiles) {
+        const realFile = realpathOrNull(cachedFile) ?? cachedFile;
+        const inAdapter = realAdapterRoots.some((root) => isInside(realFile, root));
+        if (!inAdapter && !realGhostRoots.some((root) => isInside(realFile, root))) {
+            continue;
+        }
+        const location = parsePackageFromPath(realFile);
+        if (!location) {
+            continue;
+        }
+        if (!inAdapter) {
+            // Ghost's tree can hold more than one copy of a name, and any of them is
+            // the other half of the comparison, so the first one seen will do.
+            if (!ghostPackages.has(location.name)) {
+                ghostPackages.set(location.name, location.path);
+            }
+            continue;
+        }
+        // Two adapters can each bundle their own copy, so keep every location.
+        const packagePaths = adapterPackages.get(location.name) ?? new Set();
+        adapterPackages.set(location.name, packagePaths.add(location.path));
+    }
+    // Reading versions only once both sides are known costs one manifest read per
+    // reported copy, rather than one per cached file.
+    const duplicates = [];
+    for (const [name, packagePaths] of [...adapterPackages].sort(([a], [b]) => a.localeCompare(b))) {
+        const ghostPath = ghostPackages.get(name);
+        if (!ghostPath) {
+            continue;
+        }
+        const ghost = { version: readVersion(ghostPath), path: ghostPath };
+        for (const packagePath of packagePaths) {
+            duplicates.push({
+                name,
+                adapter: { version: readVersion(packagePath), path: packagePath },
+                ghost,
+            });
+        }
+    }
+    const singleCopy = new Set(mustBeSingleCopy);
+    return { duplicates, blocking: duplicates.filter(({ name }) => singleCopy.has(name)) };
+}
+/** Render a report in the same indented style as the adapter results. */
+function formatDuplicateReport({ duplicates, blocking }) {
+    if (!duplicates.length) {
+        return '  ok    no duplicate dependencies\n';
+    }
+    return [
+        `\n${duplicates.length} package(s) loaded from both an adapter and Ghost:\n`,
+        ...duplicates.map(({ name, adapter, ghost }) => `- ${name}\n` +
+            `    adapter ${adapter.version}  ${adapter.path}\n` +
+            `    ghost   ${ghost.version}  ${ghost.path}\n`),
+        '\nEach duplicate is loaded into memory twice. Have the adapter declare the\n' +
+            'package as a peer dependency of Ghost, or match the version Ghost ships,\n' +
+            'so the install can be deduplicated.\n\n',
+        blocking.length
+            ? `  FAIL  duplicate dependencies: ${blocking.map(({ name }) => name).join(', ')}\n` +
+                '        A second copy of these breaks `instanceof` against the base class\n' +
+                '        Ghost checks adapters with - they must resolve to a single copy.\n'
+            : '  ok    duplicate dependencies (none of them must be a single copy)\n',
+    ].join('');
+}

package/bin/validate-adapters.js

@@ -2,15 +2,17 @@
 "use strict";
 // Checks that custom adapters load and implement everything their base class
 // requires. Ghost only verifies an adapter fully on first use (`getAdapter`), so a
-// missing method on a storage adapter otherwise surfaces at first upload; run this
-// at image build time to fail the build instead.
+// missing method on a storage adapter otherwise surfaces at first upload - run
+// this at image build time to fail the build instead.
 //
-// Usage: bin/validate-adapters.js <type>:<AdapterClassName> ...
+// Usage: bin/validate-adapters.js [--check-duplicate-deps] <type>:<AdapterClassName> ...
 //   e.g. bin/validate-adapters.js cache:Redis sso:ProSSO storage:S3Storage
 //
 // Adapters are named explicitly rather than read from config, which may not be
 // present at build time
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_util_1 = require("node:util");
+const duplicate_deps_1 = require("./lib/duplicate-deps");
 const adapter_paths_1 = require("../core/server/services/adapter-manager/adapter-paths");
 const base_classes_1 = require("../core/server/services/adapter-manager/base-classes");
 const utils_1 = require("../core/server/services/adapter-manager/utils");
@@ -43,11 +45,47 @@ function validate(spec) {
         throw new Error(`missing method(s): ${missing.join(', ')}`);
     }
 }
-function main(specs) {
-    if (!specs.length) {
-        process.stderr.write('Usage: bin/validate-adapters.js <type>:<AdapterClassName> ...\n');
+/**
+ * Report the packages the loaded adapters brought a second copy of. Reads what the
+ * process has already loaded, so it has to run after the adapters have. In a Ghost
+ * Pro image `module.paths` reaches the `/home/ghost/node_modules` that an adapter's
+ * unbundled dependencies fall back to, which is the other side of the comparison.
+ */
+function reportDuplicateDeps() {
+    const report = (0, duplicate_deps_1.checkDuplicateDependencies)({
+        cachedFiles: (0, duplicate_deps_1.collectLoadedFiles)(Object.keys(require.cache)),
+        // The blank entry means "Ghost's own node_modules", which is the other side
+        // of the comparison rather than an adapter tree.
+        adapterRoots: adapter_paths_1.adapterPaths.filter((adapterPath) => adapterPath !== ''),
+        ghostNodeModulesRoots: module.paths,
+        mustBeSingleCopy: Object.values(base_classes_1.baseClassPackages),
+    });
+    process.stdout.write((0, duplicate_deps_1.formatDuplicateReport)(report));
+    return report.blocking.length > 0;
+}
+/** `parseArgs` is strict, so a bad option throws instead of passing for a name. */
+function parseCliArgs(argv) {
+    try {
+        return (0, node_util_1.parseArgs)({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                'check-duplicate-deps': { type: 'boolean', default: false },
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return null;
+    }
+}
+function main(argv) {
+    const parsed = parseCliArgs(argv);
+    if (!parsed?.positionals.length) {
+        process.stderr.write('Usage: bin/validate-adapters.js [--check-duplicate-deps] <type>:<AdapterClassName> ...\n');
         process.exit(1);
     }
+    const { values, positionals: specs } = parsed;
     const failures = [];
     for (const spec of specs) {
         try {
@@ -59,11 +97,17 @@ function main(specs) {
             process.stdout.write(`  FAIL  ${spec}\n`);
         }
     }
+    // Off unless asked for: a self-hosted adapter in content/adapters may
+    // legitimately bundle its own dependencies, and that must not fail anyone's
+    // build. Only the image build installing adapters itself opts in.
+    const duplicatesBlocked = values['check-duplicate-deps'] && reportDuplicateDeps();
     if (failures.length) {
         process.stderr.write(`\n${failures.length} of ${specs.length} adapter(s) failed validation:\n`);
         for (const { spec, message } of failures) {
             process.stderr.write(`- ${spec}: ${message}\n`);
         }
+    }
+    if (failures.length || duplicatesBlocked) {
         process.exit(1);
     }
     process.stdout.write(`Validated ${specs.length} adapter(s).\n`);