@camunda8/cli 4.0.0-alpha.2 → 4.0.0-alpha.4

package/dist/framework/plugins/plugin-compat.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The plugin → host version contract (#523).
+ *
+ * A plugin declares the c8ctl it needs in its own `package.json`:
+ *
+ * ```json
+ * { "engines": { "c8ctl": ">=4.0.0-alpha.1" } }
+ * ```
+ *
+ * `engines` is the conventional home for a host requirement and npm ignores
+ * engine keys it does not know, so declaring one changes nothing about how the
+ * plugin installs. The field is optional — a plugin that declares nothing is
+ * `undeclared` and behaves exactly as it did before this module existed.
+ *
+ * Why this exists: the plugin runtime grows over time (`c8ctl.npm()` is the
+ * case that prompted #523). Without a declared requirement, a plugin built
+ * against a newer runtime fails inside the plugin, at command time, with
+ * whatever error the missing API happens to raise — usually a bare
+ * `TypeError`. With one, c8ctl can say which version is needed, at install
+ * time, before anything is run.
+ *
+ * Range evaluation is delegated to `semver` — the library npm itself uses for
+ * `engines` fields — rather than hand-parsed. That gets the full npm range
+ * grammar (set unions, hyphen ranges, wildcards) for free, and correctness for
+ * the parts that are easy to get wrong by hand (prerelease ordering, 0.x caret
+ * carve-outs, build-metadata stripping). It is a genuine root dependency of
+ * this module (see `CORE_DEPENDENCIES` in
+ * `tests/unit/root-dependencies-isolation.test.ts`), not something bundled
+ * per-plugin the way a default plugin's own dependencies are.
+ *
+ * **Failing open is a design rule, not an oversight.** Three situations mean
+ * "cannot evaluate": an unpublished development build of c8ctl, a host version
+ * `semver` cannot parse, and a range `semver` cannot parse. All three yield
+ * `unverifiable` and leave the plugin fully working. Disabling a plugin over a
+ * question we could not answer would turn a diagnostic into an outage.
+ *
+ * **Prereleases participate in ranges**, unlike `npm install`'s default. A host
+ * on `4.1.0-alpha.3` satisfies `>=4.0.0-alpha.1` here; npm would exclude it
+ * without `includePrerelease`. c8ctl publishes alphas, so the npm default would
+ * disable plugins on the exact channel their requirement was written for. `^`
+ * and `~` still desugar to npm's prerelease-excluding upper bound (`^4.1.0` is
+ * `>=4.1.0 <5.0.0-0`); an explicit `<5.0.0` does not, because it says what it
+ * says.
+ */
+/** The `engines` key a plugin declares its host requirement under. */
+export declare const HOST_ENGINE_KEY = "c8ctl";
+/**
+ * - `undeclared` — the plugin declared no requirement (the common case).
+ * - `satisfied` — the running c8ctl meets it.
+ * - `incompatible` — it does not. The plugin's commands are disabled and
+ *   `message` explains why.
+ * - `unverifiable` — the question could not be answered; the plugin keeps
+ *   working and `message` says what was skipped.
+ */
+export type HostCompatStatus = "undeclared" | "satisfied" | "incompatible" | "unverifiable";
+export interface HostCompatVerdict {
+    status: HostCompatStatus;
+    /** The declared range, verbatim, when there was one. */
+    range?: string;
+    /** Ready-to-print explanation. Set for `incompatible` and `unverifiable`. */
+    message?: string;
+    /**
+     * Why the question could not be answered, on `unverifiable` only.
+     *
+     * Callers log these differently on purpose. `unreadable-range` is a mistake
+     * in a published plugin and somebody should hear about it, so it warns.
+     * `dev-build` is the expected state of every source checkout, and
+     * `unreadable-host-version` is a property of the host rather than of the
+     * plugin it would name — warning about either would blame a plugin for
+     * something its author cannot fix, on every single invocation.
+     */
+    reason?: "dev-build" | "unreadable-range" | "unreadable-host-version";
+}
+/**
+ * Whether `version` satisfies `range`, evaluated by `semver` with
+ * `includePrerelease` on (see the module doc for why).
+ *
+ * Returns `null` when either `version` or `range` cannot be parsed — callers
+ * must treat that as "cannot evaluate", never as "not satisfied".
+ */
+export declare function satisfiesRange({ version, range, }: {
+    version: string;
+    range: string;
+}): boolean | null;
+/**
+ * Read a plugin's declared host requirement from its parsed `package.json`.
+ * Returns `null` for anything that is not a non-empty string, so a malformed
+ * declaration is indistinguishable from no declaration at all.
+ */
+export declare function readHostRequirement(packageJson: unknown): string | null;
+/**
+ * Decide whether a plugin can run on this c8ctl.
+ *
+ * `hostVersion` is a parameter rather than a read of the runtime singleton so
+ * both this decision and the loader that consumes it can be tested against
+ * arbitrary versions — a source checkout always reports the unpublished
+ * development version, which by design answers `unverifiable`.
+ */
+export declare function checkHostCompat({ pluginName, declaredRange, hostVersion, }: {
+    pluginName: string;
+    declaredRange: string | null;
+    hostVersion: string;
+}): HostCompatVerdict;
+//# sourceMappingURL=plugin-compat.d.ts.map

package/dist/framework/plugins/plugin-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-compat.d.ts","sourceRoot":"","sources":["../../../src/framework/plugins/plugin-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,sEAAsE;AACtE,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACzB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,cAAc,CAAC;AAElB,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,gBAAgB,CAAC;IACzB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAC9B,OAAO,EACP,KAAK,GACL,EAAE;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,GAAG,IAAI,CAIjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAQvE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC/B,UAAU,EACV,aAAa,EACb,WAAW,GACX,EAAE;IACF,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACpB,GAAG,iBAAiB,CA2DpB"}

package/dist/framework/plugins/plugin-compat.js

@@ -0,0 +1,141 @@
+/**
+ * The plugin → host version contract (#523).
+ *
+ * A plugin declares the c8ctl it needs in its own `package.json`:
+ *
+ * ```json
+ * { "engines": { "c8ctl": ">=4.0.0-alpha.1" } }
+ * ```
+ *
+ * `engines` is the conventional home for a host requirement and npm ignores
+ * engine keys it does not know, so declaring one changes nothing about how the
+ * plugin installs. The field is optional — a plugin that declares nothing is
+ * `undeclared` and behaves exactly as it did before this module existed.
+ *
+ * Why this exists: the plugin runtime grows over time (`c8ctl.npm()` is the
+ * case that prompted #523). Without a declared requirement, a plugin built
+ * against a newer runtime fails inside the plugin, at command time, with
+ * whatever error the missing API happens to raise — usually a bare
+ * `TypeError`. With one, c8ctl can say which version is needed, at install
+ * time, before anything is run.
+ *
+ * Range evaluation is delegated to `semver` — the library npm itself uses for
+ * `engines` fields — rather than hand-parsed. That gets the full npm range
+ * grammar (set unions, hyphen ranges, wildcards) for free, and correctness for
+ * the parts that are easy to get wrong by hand (prerelease ordering, 0.x caret
+ * carve-outs, build-metadata stripping). It is a genuine root dependency of
+ * this module (see `CORE_DEPENDENCIES` in
+ * `tests/unit/root-dependencies-isolation.test.ts`), not something bundled
+ * per-plugin the way a default plugin's own dependencies are.
+ *
+ * **Failing open is a design rule, not an oversight.** Three situations mean
+ * "cannot evaluate": an unpublished development build of c8ctl, a host version
+ * `semver` cannot parse, and a range `semver` cannot parse. All three yield
+ * `unverifiable` and leave the plugin fully working. Disabling a plugin over a
+ * question we could not answer would turn a diagnostic into an outage.
+ *
+ * **Prereleases participate in ranges**, unlike `npm install`'s default. A host
+ * on `4.1.0-alpha.3` satisfies `>=4.0.0-alpha.1` here; npm would exclude it
+ * without `includePrerelease`. c8ctl publishes alphas, so the npm default would
+ * disable plugins on the exact channel their requirement was written for. `^`
+ * and `~` still desugar to npm's prerelease-excluding upper bound (`^4.1.0` is
+ * `>=4.1.0 <5.0.0-0`); an explicit `<5.0.0` does not, because it says what it
+ * says.
+ */
+import semver from "semver";
+import { isRecord, isUnversionedDevBuild } from "../../core/index.js";
+/** The `engines` key a plugin declares its host requirement under. */
+export const HOST_ENGINE_KEY = "c8ctl";
+/**
+ * Whether `version` satisfies `range`, evaluated by `semver` with
+ * `includePrerelease` on (see the module doc for why).
+ *
+ * Returns `null` when either `version` or `range` cannot be parsed — callers
+ * must treat that as "cannot evaluate", never as "not satisfied".
+ */
+export function satisfiesRange({ version, range, }) {
+    if (semver.valid(version) === null)
+        return null;
+    if (semver.validRange(range) === null)
+        return null;
+    return semver.satisfies(version, range, { includePrerelease: true });
+}
+/**
+ * Read a plugin's declared host requirement from its parsed `package.json`.
+ * Returns `null` for anything that is not a non-empty string, so a malformed
+ * declaration is indistinguishable from no declaration at all.
+ */
+export function readHostRequirement(packageJson) {
+    if (!isRecord(packageJson))
+        return null;
+    const { engines } = packageJson;
+    if (!isRecord(engines))
+        return null;
+    const declared = engines[HOST_ENGINE_KEY];
+    if (typeof declared !== "string")
+        return null;
+    const trimmed = declared.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Decide whether a plugin can run on this c8ctl.
+ *
+ * `hostVersion` is a parameter rather than a read of the runtime singleton so
+ * both this decision and the loader that consumes it can be tested against
+ * arbitrary versions — a source checkout always reports the unpublished
+ * development version, which by design answers `unverifiable`.
+ */
+export function checkHostCompat({ pluginName, declaredRange, hostVersion, }) {
+    if (declaredRange === null)
+        return { status: "undeclared" };
+    if (isUnversionedDevBuild(hostVersion)) {
+        return {
+            status: "unverifiable",
+            range: declaredRange,
+            reason: "dev-build",
+            message: `Plugin '${pluginName}' requires c8ctl ${declaredRange}, but this is an unpublished ` +
+                `development build (${hostVersion}) whose version says nothing about its API surface. ` +
+                "Skipping the check — the plugin stays enabled.",
+        };
+    }
+    // Checked before the range, because `satisfiesRange` answers `null` for both
+    // "unreadable range" and "unreadable version" and only the plugin author can
+    // act on the first. Collapsing them blames a plugin for the host's version
+    // string — and since the scaffold ships `engines.c8ctl: "*"`, any host whose
+    // version this module cannot parse (a fork, a nightly tag, a hand-edited
+    // manifest) would make every scaffolded plugin warn about itself.
+    if (semver.valid(hostVersion) === null) {
+        return {
+            status: "unverifiable",
+            range: declaredRange,
+            reason: "unreadable-host-version",
+            message: `Plugin '${pluginName}' requires c8ctl ${declaredRange}, but this c8ctl reports its version ` +
+                `as '${hostVersion}', which is not a version this check can compare. Skipping the check — ` +
+                "the plugin stays enabled.",
+        };
+    }
+    const satisfied = satisfiesRange({
+        version: hostVersion,
+        range: declaredRange,
+    });
+    if (satisfied === null) {
+        return {
+            status: "unverifiable",
+            range: declaredRange,
+            reason: "unreadable-range",
+            message: `Plugin '${pluginName}' declares engines.${HOST_ENGINE_KEY} '${declaredRange}', which is not a ` +
+                "version range c8ctl understands (npm's semver range syntax — see " +
+                "https://github.com/npm/node-semver#ranges). Ignoring the requirement — the plugin stays enabled.",
+        };
+    }
+    if (satisfied)
+        return { status: "satisfied", range: declaredRange };
+    return {
+        status: "incompatible",
+        range: declaredRange,
+        message: `Plugin '${pluginName}' requires c8ctl ${declaredRange}, but this is c8ctl ${hostVersion}. ` +
+            "Upgrade with 'npm install -g @camunda8/cli@latest', or install a plugin release that " +
+            `supports c8ctl ${hostVersion}.`,
+    };
+}
+//# sourceMappingURL=plugin-compat.js.map

package/dist/framework/plugins/plugin-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-compat.js","sourceRoot":"","sources":["../../../src/framework/plugins/plugin-compat.ts"],"names":[],"mappings":"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"}

package/dist/framework/plugins/plugin-loader.d.ts

@@ -114,14 +114,20 @@ export interface PluginCommandMeta {
  * surfaced by `c8ctl doctor plugin` (#363). Two flavours:
  *
  * - `command-name`: two plugins exported a command under the same name.
- *   The earlier-loaded plugin's command stays in dispatch; the later
- *   plugin's was dropped. `winner`/`loser` reflect that ordering.
+ *   Normally the earlier-loaded plugin's command stays in dispatch and the
+ *   later plugin's was dropped, so `winner`/`loser` reflect load order. The
+ *   exception is a `hostIncompatible` incumbent (#523), which loses the name
+ *   to a working newcomer regardless of order.
  * - `plugin-name`: two plugins shared the same `package.json#name`.
  *   The entire later plugin was rejected (its module body was never
  *   imported); `command` is undefined for this kind.
  *
- * The doctor command is the only consumer; the loader appends to this
- * list as it discovers collisions and never reads from it. Cleared by
+ * `winner` always names the plugin that ends up owning the command. When a
+ * takeover supersedes an earlier decision, `rejectDuplicateCommandNames`
+ * re-points the affected records rather than dropping them — the losers are
+ * still losers, and erasing their records would hide a real collision.
+ *
+ * The doctor command is the only external consumer. Cleared by
  * `clearLoadedPlugins()` so test fixtures stay isolated.
  */
 export interface PluginCollision {
@@ -130,6 +136,30 @@ export interface PluginCollision {
     loser: string;
     command?: string;
 }
+/**
+ * Structured record of a plugin whose declared `engines.c8ctl` this c8ctl does
+ * not satisfy (#523), surfaced by `c8ctl doctor plugin`.
+ *
+ * The plugin stays loaded and keeps its place in help — what changed is that its
+ * commands now refuse to run and print `message` instead (bar any a working
+ * plugin has taken over). Removing it from help would trade one confusing
+ * failure ("unknown command os") for another; leaving it visible means the
+ * command that a user or an agent already knows about is the one that explains
+ * itself.
+ *
+ * The loader only appends and the doctor command only reads;
+ * `clearLoadedPlugins()` resets it so test fixtures stay isolated.
+ */
+export interface PluginIncompatibility {
+    plugin: string;
+    /** The plugin's own version, for "which release did this come from". */
+    pluginVersion: string;
+    /** The declared range, verbatim. */
+    required: string;
+    /** The c8ctl the requirement was evaluated against. */
+    running: string;
+    message: string;
+}
 /**
  * Compute the candidate `default-plugins` directories, relative to the
  * directory containing this loader module.
@@ -149,8 +179,14 @@ export interface PluginCollision {
 export declare function defaultPluginsCandidateDirs(loaderDir: string): string[];
 /**
  * Load all installed plugins from global plugins directory
+ *
+ * `hostVersion` defaults to the running c8ctl and exists so the `engines.c8ctl`
+ * enforcement (#523) can be exercised against other versions: a source checkout
+ * reports the unpublished development version, which by design skips the check.
  */
-export declare function loadInstalledPlugins(): Promise<void>;
+export declare function loadInstalledPlugins({ hostVersion, }?: {
+    hostVersion?: string;
+}): Promise<void>;
 /**
  * Get all loaded plugin commands
  */
@@ -216,6 +252,16 @@ export declare function getPluginCommandsInfo(): PluginCommandInfo[];
  * (#366). Used by the dispatcher to gate the strip-and-forward path.
  */
 export declare function isPassthroughPluginCommand(commandName: string): boolean;
+/**
+ * True if the named command belongs to a plugin disabled by its declared
+ * `engines.c8ctl` (#523).
+ *
+ * The dispatcher uses this to skip flag validation for such a command: its
+ * handler exists only to report which c8ctl the plugin needs, and rejecting the
+ * invocation for a missing required flag first would replace that explanation
+ * with an instruction the user cannot usefully follow.
+ */
+export declare function isHostIncompatiblePluginCommand(commandName: string): boolean;
 /**
  * Clear all loaded plugins (useful for testing and after uninstall)
  */
@@ -228,6 +274,12 @@ export declare function clearLoadedPlugins(): void;
  * collisions.
  */
 export declare function getPluginCollisions(): readonly Readonly<PluginCollision>[];
+/**
+ * Snapshot of plugins whose declared `engines.c8ctl` this c8ctl does not
+ * satisfy (#523). Same defensive-copy contract as
+ * {@link getPluginCollisions}; order reflects load order.
+ */
+export declare function getPluginIncompatibilities(): readonly Readonly<PluginIncompatibility>[];
 /**
  * Snapshot of currently loaded plugins (#363). Returns the canonical
  * `package.json#name` of each plugin together with the command names
@@ -238,6 +290,8 @@ export declare function getPluginCollisions(): readonly Readonly<PluginCollision
 export interface LoadedPluginSummary {
     name: string;
     commands: string[];
+    /** Declared `engines.c8ctl` range, when the plugin declared one (#523). */
+    requires?: string;
 }
 export declare function getLoadedPluginSummaries(): LoadedPluginSummary[];
 //# sourceMappingURL=plugin-loader.d.ts.map

package/dist/framework/plugins/plugin-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../../src/framework/plugins/plugin-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../../src/framework/plugins/plugin-loader.ts"],"names":[],"mappings":"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"}

package/dist/framework/plugins/plugin-loader.js

@@ -11,9 +11,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { c8ctl, ensurePluginsDir, getLogger, } from "../../core/index.js";
+import { c8ctl, ensurePluginsDir, getLogger, SilentError, } from "../../core/index.js";
+import { checkHostCompat, readHostRequirement } from "./plugin-compat.js";
 const loadedPlugins = new Map();
 const pluginCollisions = [];
+const pluginIncompatibilities = [];
 /**
  * Validate the passthrough/flags mutual-exclusion rule (#366). Removes
  * offending commands from the registered set so they cannot be invoked,
@@ -97,6 +99,11 @@ function validatePassthroughCommands(plugin) {
  * different name. Default plugins always load first, so user-installed
  * plugins cannot override default commands by name.
  *
+ * **One exception (#523):** an incumbent whose declared `engines.c8ctl` this
+ * c8ctl does not satisfy loses the name to a working newcomer — its command
+ * could only ever throw. A default plugin can never be on the losing side of
+ * this, since `enforceHostRequirement` runs for installed plugins only.
+ *
  * This guarantees that the merged map returned by `getPluginCommands()`
  * has a single owning plugin per command name, which keeps dispatch and
  * `isPassthroughPluginCommand()` consistent: the help renderer and the
@@ -110,19 +117,54 @@ function rejectDuplicateCommandNames(plugin) {
     const logger = getLogger();
     for (const commandName of Object.keys(plugin.commands)) {
         for (const existing of loadedPlugins.values()) {
-            if (Object.hasOwn(existing.commands, commandName)) {
-                logger.warn(`Plugin '${plugin.name}' tried to register command '${commandName}' but it is ` +
-                    `already provided by plugin '${existing.name}'. The first registration wins; ` +
-                    `dropping the duplicate from '${plugin.name}'.`);
+            if (!Object.hasOwn(existing.commands, commandName))
+                continue;
+            // One exception to first-registration-wins: an incumbent that cannot
+            // run on this c8ctl (#523) yields to a newcomer that can. Otherwise
+            // load order — lexicographic by package path — would decide that a
+            // disabled `aaa-plugin` keeps the command name and a working
+            // `zzz-plugin` loses it, leaving the user with a command that only
+            // ever throws while a functioning implementation sits unreachable.
+            // The incumbent keeps its plugin entry in help, but loses this command.
+            if (existing.hostIncompatible && !plugin.hostIncompatible) {
+                logger.debug(`Plugin '${plugin.name}' takes over command '${commandName}' from ` +
+                    `'${existing.name}', which is disabled on this c8ctl.`);
+                // Re-point, don't delete. Earlier records for this name are still
+                // true about who *lost* it — a third plugin that lost to the
+                // incumbent has genuinely lost the command — but their `winner` is
+                // now stale. Dropping them would erase that plugin's collision from
+                // `doctor plugin` entirely; leaving them unedited would credit a win
+                // to a plugin that no longer owns the name.
+                for (const record of pluginCollisions) {
+                    if (record.kind === "command-name" &&
+                        record.command === commandName &&
+                        record.winner === existing.name) {
+                        record.winner = plugin.name;
+                    }
+                }
                 pluginCollisions.push({
                     kind: "command-name",
-                    winner: existing.name,
-                    loser: plugin.name,
+                    winner: plugin.name,
+                    loser: existing.name,
                     command: commandName,
                 });
-                delete plugin.commands[commandName];
-                break;
+                // `continue`, not `break`: this function is what maintains "at most
+                // one loaded plugin owns a given command name", so there is nothing
+                // further to find for this name.
+                delete existing.commands[commandName];
+                continue;
             }
+            logger.warn(`Plugin '${plugin.name}' tried to register command '${commandName}' but it is ` +
+                `already provided by plugin '${existing.name}'. The first registration wins; ` +
+                `dropping the duplicate from '${plugin.name}'.`);
+            pluginCollisions.push({
+                kind: "command-name",
+                winner: existing.name,
+                loser: plugin.name,
+                command: commandName,
+            });
+            delete plugin.commands[commandName];
+            break;
         }
     }
 }
@@ -154,6 +196,73 @@ function isDuplicatePluginName(pluginName) {
     }
     return false;
 }
+/**
+ * Enforce a plugin's declared `engines.c8ctl` (#523).
+ *
+ * On an unmet requirement, every command the plugin registered is replaced with
+ * a handler that throws the explanation. The plugin stays in `loadedPlugins` and
+ * therefore in help — see {@link PluginIncompatibility} for why disabling is
+ * done this way round.
+ *
+ * Runs *before* the collision passes, which read `hostIncompatible` to let a
+ * disabled incumbent lose a command name to a working newcomer. Takes the host
+ * version as an argument so the behaviour is testable against versions other
+ * than whatever this build happens to report.
+ *
+ * Mutates `plugin.commands` in place.
+ */
+function enforceHostRequirement(plugin, hostVersion) {
+    const logger = getLogger();
+    const verdict = checkHostCompat({
+        pluginName: plugin.name,
+        declaredRange: plugin.hostRequirement ?? null,
+        hostVersion,
+    });
+    if (verdict.status === "unverifiable") {
+        // Only an unreadable *range* warns: that is an authoring mistake, and the
+        // plugin is silently not getting the guarantee it asked for. The other two
+        // reasons are properties of the host — a source checkout, or a version
+        // string this check cannot parse — and would name a blameless plugin on
+        // every single invocation.
+        const message = verdict.message ?? "";
+        if (verdict.reason === "unreadable-range")
+            logger.warn(message);
+        else
+            logger.debug(message);
+        return;
+    }
+    if (verdict.status !== "incompatible")
+        return;
+    const message = verdict.message ?? "";
+    plugin.hostIncompatible = true;
+    // Debug, not warn: unlike a dropped colliding command — which has no other
+    // channel to announce itself — a disabled plugin explains itself the moment
+    // one of its commands is used, and `doctor plugin` lists it on demand.
+    // Warning on every unrelated invocation would be noise with no new signal.
+    logger.debug(message);
+    pluginIncompatibilities.push({
+        plugin: plugin.name,
+        pluginVersion: plugin.version,
+        required: verdict.range ?? "",
+        running: hostVersion,
+        message,
+    });
+    // SilentError: the message is the whole diagnosis and is rendered as one
+    // error line by the top-level handler. A plain Error would come back out as
+    // "Unexpected error" plus a stack trace — the shape of failure this check
+    // exists to replace.
+    const refuse = async () => {
+        throw new SilentError(message);
+    };
+    for (const commandName of Object.keys(plugin.commands)) {
+        const command = plugin.commands[commandName];
+        // Keep the `{ flags, handler }` shape intact: help rendering and flag
+        // parsing both branch on it, and a command that loses its flags would
+        // fail with a parse error instead of the explanation.
+        plugin.commands[commandName] =
+            typeof command === "function" ? refuse : { ...command, handler: refuse };
+    }
+}
 /**
  * Compute the candidate `default-plugins` directories, relative to the
  * directory containing this loader module.
@@ -269,8 +378,12 @@ async function loadDefaultPlugins() {
 }
 /**
  * Load all installed plugins from global plugins directory
+ *
+ * `hostVersion` defaults to the running c8ctl and exists so the `engines.c8ctl`
+ * enforcement (#523) can be exercised against other versions: a source checkout
+ * reports the unpublished development version, which by design skips the check.
  */
-export async function loadInstalledPlugins() {
+export async function loadInstalledPlugins({ hostVersion = c8ctl.version, } = {}) {
     const logger = getLogger();
     // Expose the runtime to plugins via globalThis.
     // C8ctl implements C8ctlPluginRuntime directly — no monkey-patching needed.
@@ -379,13 +492,21 @@ export async function loadInstalledPlugins() {
                 logger.debug(`Loading plugin from: ${pluginUrl}`);
                 const plugin = await import(__rewriteRelativeImportExtension(pluginUrl));
                 if (plugin.commands && typeof plugin.commands === "object") {
+                    const hostRequirement = readHostRequirement(packageJson);
                     const loaded = {
                         name: pluginName,
                         version: pluginVersion,
                         commands: { ...plugin.commands },
                         metadata: plugin.metadata || {},
+                        ...(hostRequirement === null ? {} : { hostRequirement }),
                     };
                     validatePassthroughCommands(loaded);
+                    // Before the collision pass, which needs to know whether either
+                    // side of a command-name clash is disabled. Installed plugins
+                    // only: a default plugin ships inside the c8ctl package, so its
+                    // host is itself and there is no version skew for
+                    // `engines.c8ctl` (#523) to catch.
+                    enforceHostRequirement(loaded, hostVersion);
                     rejectDuplicateCommandNames(loaded);
                     loadedPlugins.set(pluginName, loaded);
                     const commandNames = Object.keys(loaded.commands);
@@ -509,12 +630,31 @@ export function isPassthroughPluginCommand(commandName) {
     }
     return false;
 }
+/**
+ * True if the named command belongs to a plugin disabled by its declared
+ * `engines.c8ctl` (#523).
+ *
+ * The dispatcher uses this to skip flag validation for such a command: its
+ * handler exists only to report which c8ctl the plugin needs, and rejecting the
+ * invocation for a missing required flag first would replace that explanation
+ * with an instruction the user cannot usefully follow.
+ */
+export function isHostIncompatiblePluginCommand(commandName) {
+    for (const plugin of loadedPlugins.values()) {
+        if (!Object.hasOwn(plugin.commands, commandName))
+            continue;
+        if (plugin.hostIncompatible === true)
+            return true;
+    }
+    return false;
+}
 /**
  * Clear all loaded plugins (useful for testing and after uninstall)
  */
 export function clearLoadedPlugins() {
     loadedPlugins.clear();
     pluginCollisions.length = 0;
+    pluginIncompatibilities.length = 0;
 }
 /**
  * Snapshot of plugin collisions detected at load time (#363). Returns
@@ -526,12 +666,23 @@ export function clearLoadedPlugins() {
 export function getPluginCollisions() {
     return Object.freeze(pluginCollisions.map((c) => Object.freeze({ ...c })));
 }
+/**
+ * Snapshot of plugins whose declared `engines.c8ctl` this c8ctl does not
+ * satisfy (#523). Same defensive-copy contract as
+ * {@link getPluginCollisions}; order reflects load order.
+ */
+export function getPluginIncompatibilities() {
+    return Object.freeze(pluginIncompatibilities.map((i) => Object.freeze({ ...i })));
+}
 export function getLoadedPluginSummaries() {
     const summaries = [];
     for (const plugin of loadedPlugins.values()) {
         summaries.push({
             name: plugin.name,
             commands: Object.keys(plugin.commands),
+            ...(plugin.hostRequirement === undefined
+                ? {}
+                : { requires: plugin.hostRequirement }),
         });
     }
     return summaries;