@camunda8/cli 2.8.0-alpha.9 → 3.0.0

package/dist/plugin-loader.d.ts

@@ -1,16 +1,127 @@
 /**
  * Plugin loader for dynamic command loading
  */
+import type { CamundaClient } from "@camunda8/orchestration-cluster-api";
 import type { FlagDef } from "./command-registry.ts";
-type CommandHandler = (args: string[], flags?: Record<string, unknown>) => Promise<void>;
-interface CommandWithFlags {
+import { type Logger, type OutputMode } from "./logger.ts";
+/**
+ * Typed, documented host context passed to plugin command handlers as
+ * the third argument (#377).
+ *
+ * Reflects every member of `GLOBAL_FLAGS` whose value is meaningful to
+ * a plugin handler; `help` and `version` are intentionally absent
+ * because they are intercepted by the host before dispatch. The
+ * class-scoped contract test
+ * (`tests/unit/plugin-host-context-contract.test.ts`) pins this
+ * relationship.
+ *
+ * `client` is exposed as a lazy getter so plugins that never need a
+ * Camunda client (e.g. local-only utilities, session inspectors) do
+ * not trigger credential resolution simply by receiving the ctx.
+ *
+ * Plugins authored before #377 use the two-argument signature
+ * `(args, flags)` — the third argument is additive and JavaScript's
+ * variadic call semantics keep those handlers working unchanged.
+ */
+export interface PluginCtx {
+    /**
+     * Active profile name (from `--profile` or session), or `undefined` when
+     * neither was set. Plugins should pass this through to `createClient()` /
+     * `resolveTenantId()` verbatim so env-var-only configurations (no
+     * profile, just `CAMUNDA_*` env vars) resolve the same way they do for
+     * built-in commands.
+     */
+    profile: string | undefined;
+    /** True when `--dry-run` is set. Plugins SHOULD honour this. */
+    dryRun: boolean;
+    /** True when `--verbose` is set. */
+    verbose: boolean;
+    /** Effective output mode (`--json` toggles to `json`). */
+    outputMode: OutputMode;
+    /** Parsed `--fields a,b,c` list, or undefined when not set. */
+    fields?: string[];
+    /** Host logger — use `logger.json(...)` for structured output. */
+    logger: Logger;
+    /** Lazily-resolved Camunda client. Reading triggers credential resolution. */
+    readonly client: CamundaClient;
+}
+export type CommandHandler = (args: string[], flags?: Record<string, unknown>, ctx?: PluginCtx) => Promise<void>;
+export interface CommandWithFlags {
     flags: Record<string, FlagDef>;
     handler: CommandHandler;
 }
-type PluginCommand = CommandHandler | CommandWithFlags;
-interface PluginCommands {
+export type PluginCommand = CommandHandler | CommandWithFlags;
+export interface PluginCommands {
     [commandName: string]: PluginCommand;
 }
+export interface PluginMetadata {
+    name?: string;
+    description?: string;
+    commands?: {
+        [commandName: string]: PluginCommandMeta;
+    };
+}
+/**
+ * Per-command plugin metadata.
+ *
+ * A plugin command is **either** metadata-driven (declares typed flags via
+ * the `{ flags, handler }` command form) **or** a passthrough command
+ * (`passthrough: true` + `passthroughHint`). Mutually exclusive — see
+ * #251 / #366. Declaring both is rejected at load time.
+ */
+export interface PluginCommandMeta {
+    description?: string;
+    helpDescription?: string;
+    examples?: {
+        command: string;
+        description: string;
+    }[];
+    /** Subcommands for shell completion (e.g. cluster → start, stop, status). */
+    subcommands?: {
+        name: string;
+        description: string;
+    }[];
+    /**
+     * If true, c8ctl strips GLOBAL_FLAGS from argv and forwards everything
+     * else verbatim to the bare-function handler. Help and JSON help
+     * advertise the boundary explicitly.
+     *
+     * MUST NOT appear together with the `{ flags, handler }` command form;
+     * the load-time validator drops any command that declares both.
+     */
+    passthrough?: boolean;
+    /**
+     * Required when `passthrough` is true. Short text rendered in help that
+     * advertises the boundary, e.g. "Forwards args to `kubectl`".
+     */
+    passthroughHint?: string;
+    /**
+     * Optional documentation-only flag list rendered in help under
+     * passthrough commands. NOT parsed by c8ctl.
+     */
+    flagsHint?: string[];
+}
+/**
+ * Structured record of a load-time collision between two plugins,
+ * 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.
+ * - `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
+ * `clearLoadedPlugins()` so test fixtures stay isolated.
+ */
+export interface PluginCollision {
+    kind: "command-name" | "plugin-name";
+    winner: string;
+    loser: string;
+    command?: string;
+}
 /**
  * Load all installed plugins from global plugins directory
  */
@@ -20,9 +131,24 @@ export declare function loadInstalledPlugins(): Promise<void>;
  */
 export declare function getPluginCommands(): PluginCommands;
 /**
- * Execute a plugin command if it exists
+ * Execute a plugin command if it exists.
+ *
+ * `ctx` is the typed host context introduced in #377. When provided it
+ * is passed as the third handler argument; legacy two-argument
+ * handlers ignore it. When omitted the call site is treating the
+ * plugin as a fire-and-forget passthrough/help-render shim and
+ * intentionally does not construct a client.
+ */
+export declare function executePluginCommand(commandName: string, args: string[], flags?: Record<string, unknown>, ctx?: PluginCtx): Promise<boolean>;
+/**
+ * Look up the loaded version of a plugin by command name. Returns
+ * `undefined` if no plugin owns the command. Used by `--version` on a
+ * plugin verb to print the plugin's package version (#377).
  */
-export declare function executePluginCommand(commandName: string, args: string[], flags?: Record<string, unknown>): Promise<boolean>;
+export declare function getPluginVersionForCommand(commandName: string): {
+    pluginName: string;
+    version: string;
+} | undefined;
 /**
  * Check if a command is provided by a plugin
  */
@@ -37,7 +163,10 @@ export declare function getPluginCommandNames(): string[];
 export interface PluginCommandInfo {
     commandName: string;
     pluginName: string;
+    /** Plugin package version (`package.json#version`). */
+    pluginVersion: string;
     description?: string;
+    helpDescription?: string;
     examples?: {
         command: string;
         description: string;
@@ -47,11 +176,43 @@ export interface PluginCommandInfo {
         name: string;
         description: string;
     }[];
+    /** True when the command opted into the #366 passthrough contract. */
+    passthrough?: boolean;
+    /** Required when passthrough is true — short text that names the boundary. */
+    passthroughHint?: string;
+    /** Optional documentation-only flag list rendered under passthrough help. */
+    flagsHint?: string[];
+    /** Typed flag declarations for flag-aware (non-passthrough) commands. */
+    flags?: Record<string, FlagDef>;
 }
 export declare function getPluginCommandsInfo(): PluginCommandInfo[];
+/**
+ * True if the named command is a registered passthrough plugin command
+ * (#366). Used by the dispatcher to gate the strip-and-forward path.
+ */
+export declare function isPassthroughPluginCommand(commandName: string): boolean;
 /**
  * Clear all loaded plugins (useful for testing and after uninstall)
  */
 export declare function clearLoadedPlugins(): void;
-export {};
+/**
+ * Snapshot of plugin collisions detected at load time (#363). Returns
+ * a deep defensive copy of frozen records so callers cannot mutate
+ * the loader's bookkeeping (neither the array nor the entries).
+ * Order reflects the order in which the loader observed the
+ * collisions.
+ */
+export declare function getPluginCollisions(): readonly Readonly<PluginCollision>[];
+/**
+ * Snapshot of currently loaded plugins (#363). Returns the canonical
+ * `package.json#name` of each plugin together with the command names
+ * it actually registered (after duplicate-name rejection). Used by
+ * `c8ctl doctor plugin` to render an authoritative view of what was
+ * loaded vs. what was dropped.
+ */
+export interface LoadedPluginSummary {
+    name: string;
+    commands: string[];
+}
+export declare function getLoadedPluginSummaries(): LoadedPluginSummary[];
 //# sourceMappingURL=plugin-loader.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../src/plugin-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAKrD,KAAK,cAAc,GAAG,CACrB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,UAAU,gBAAgB;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC;CACxB;AAED,KAAK,aAAa,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAEvD,UAAU,cAAc;IACvB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAAC;CACrC;AAiHD;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CA2H1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAQlD;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACzC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD,6EAA6E;IAC7E,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD;AAED,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAgB3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../src/plugin-loader.ts"],"names":[],"mappings":"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"}

package/dist/plugin-loader.js

@@ -15,6 +15,147 @@ import { ensurePluginsDir } from "./config.js";
 import { getLogger } from "./logger.js";
 import { c8ctl } from "./runtime.js";
 const loadedPlugins = new Map();
+const pluginCollisions = [];
+/**
+ * Validate the passthrough/flags mutual-exclusion rule (#366). Removes
+ * offending commands from the registered set so they cannot be invoked,
+ * and emits a `logger.warn` naming the plugin and command so the
+ * misconfiguration is visible at startup.
+ *
+ * The contract: a command MUST NOT declare `passthrough: true` AND use the
+ * `{ flags, handler }` form. Pick one. A passthrough command without a
+ * `passthroughHint` is also rejected (the hint is what makes the boundary
+ * legible to users and agents).
+ *
+ * Mutates `plugin.commands` in place. Safe to call after each plugin is
+ * loaded.
+ */
+function validatePassthroughCommands(plugin) {
+    const logger = getLogger();
+    const meta = plugin.metadata?.commands ?? {};
+    for (const commandName of Object.keys(plugin.commands)) {
+        const commandMeta = meta[commandName];
+        if (commandMeta?.passthrough === undefined)
+            continue;
+        // `passthrough: false` is equivalent to "not opted in" — silently
+        // skip. Any other non-`true` value (e.g. the string "true", a
+        // number) is a contract violation: dispatch and help both gate on
+        // `=== true`, so a truthy non-true value would silently disagree
+        // with them. Reject loudly at load time.
+        if (commandMeta.passthrough === false)
+            continue;
+        if (commandMeta.passthrough !== true) {
+            logger.warn(`Plugin '${plugin.name}' command '${commandName}' has metadata.passthrough set to ` +
+                `${JSON.stringify(commandMeta.passthrough)} but the contract requires the boolean ` +
+                "literal `true` (or `false` / omitted to opt out). Dropping this command (#366).");
+            delete plugin.commands[commandName];
+            continue;
+        }
+        const cmd = plugin.commands[commandName];
+        const hasFlagsForm = typeof cmd !== "function";
+        if (hasFlagsForm) {
+            logger.warn(`Plugin '${plugin.name}' command '${commandName}' declares both passthrough:true AND flags. ` +
+                "Pick one \u2014 a passthrough command must use the bare-function handler form. " +
+                "Dropping this command (#366).");
+            delete plugin.commands[commandName];
+            continue;
+        }
+        if (typeof commandMeta.passthroughHint !== "string" ||
+            commandMeta.passthroughHint.trim() === "") {
+            logger.warn(`Plugin '${plugin.name}' command '${commandName}' declares passthrough:true ` +
+                "but is missing a non-empty passthroughHint. The hint is required so help and " +
+                "agents can advertise the boundary. Dropping this command (#366).");
+            delete plugin.commands[commandName];
+            continue;
+        }
+        // `flagsHint` is documentation-only and consumed by the help
+        // renderer, which assumes `string[]`. Validate the shape here so a
+        // mis-typed value can't reach the renderer. The field is optional;
+        // invalid shapes are stripped (not fatal) so the command itself
+        // continues to work — only the doc affordance is lost.
+        const flagsHint = commandMeta.flagsHint;
+        if (flagsHint !== undefined) {
+            const valid = Array.isArray(flagsHint) &&
+                flagsHint.every((entry) => typeof entry === "string");
+            if (!valid) {
+                logger.warn(`Plugin '${plugin.name}' command '${commandName}' declares metadata.flagsHint ` +
+                    "but it is not a string[]. Ignoring flagsHint (#366).");
+                delete commandMeta.flagsHint;
+            }
+        }
+    }
+}
+/**
+ * Reject duplicate plugin command names at load time. If `plugin` declares
+ * a command name that is already registered by an earlier-loaded plugin,
+ * drop it from `plugin.commands` and emit `logger.warn` naming both
+ * plugins so the conflict is visible at startup.
+ *
+ * **Conflict policy: first registration wins.** This is an explicit
+ * choice (#366) and replaces the previous implicit "last-loaded wins"
+ * behaviour produced by `Object.assign` over `loadedPlugins` in
+ * insertion order. Plugins cannot override one another by registering
+ * the same command name; if you want a different command, give it a
+ * different name. Default plugins always load first, so user-installed
+ * plugins cannot override default commands by name.
+ *
+ * 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
+ * runtime always agree on which plugin handles a given verb.
+ *
+ * Mutates `plugin.commands` in place. Safe to call after each plugin is
+ * loaded; relies on `loadedPlugins` already containing previously-loaded
+ * plugins.
+ */
+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}'.`);
+                pluginCollisions.push({
+                    kind: "command-name",
+                    winner: existing.name,
+                    loser: plugin.name,
+                    command: commandName,
+                });
+                delete plugin.commands[commandName];
+                break;
+            }
+        }
+    }
+}
+/**
+ * Reject a plugin whose name collides with an already-loaded plugin.
+ * This is a separate concern from the command-name collision policy
+ * tracked under #363: that policy rejects two plugins exporting the
+ * same command name, while this one rejects two plugins sharing the
+ * same `package.json#name`. Both follow first-registration-wins.
+ * Without this guard a user-installed package sharing a name with a
+ * default plugin (or with another already-loaded plugin) would
+ * silently overwrite the prior `loadedPlugins.set()` entry, bypassing
+ * the command-name policy entirely.
+ *
+ * Returns `true` when the caller should skip the load; `false` when
+ * the name is free.
+ */
+function isDuplicatePluginName(pluginName) {
+    const logger = getLogger();
+    if (loadedPlugins.has(pluginName)) {
+        logger.warn(`Plugin name '${pluginName}' is already loaded; refusing to load a second plugin ` +
+            `with the same name. The first registration wins.`);
+        pluginCollisions.push({
+            kind: "plugin-name",
+            winner: pluginName,
+            loser: pluginName,
+        });
+        return true;
+    }
+    return false;
+}
 /**
  * Load default plugins bundled with c8ctl
  */
@@ -44,7 +185,12 @@ async function loadDefaultPlugins() {
             logger.debug("No default-plugins directory found");
             return;
         }
-        const pluginDirs = readdirSync(defaultPluginsDir);
+        // Sort to make load order deterministic across filesystems/OSes.
+        // The first-registration-wins duplicate-name policy in
+        // `rejectDuplicateCommandNames` relies on this — without a stable
+        // sort, "who wins" would depend on `readdirSync()` order, which
+        // varies across platforms and filesystems.
+        const pluginDirs = readdirSync(defaultPluginsDir).sort();
         logger.debug(`Found ${pluginDirs.length} default plugin(s)`);
         for (const pluginDir of pluginDirs) {
             const pluginPath = join(defaultPluginsDir, pluginDir);
@@ -64,6 +210,17 @@ async function loadDefaultPlugins() {
                 // Read package.json
                 const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
                 const pluginName = packageJson.name || `default-${pluginDir}`;
+                const pluginVersion = typeof packageJson.version === "string" &&
+                    packageJson.version.length > 0
+                    ? packageJson.version
+                    : "0.0.0";
+                // Check for duplicate plugin name BEFORE the dynamic import
+                // so a duplicate-name plugin's module code never runs (the
+                // import has top-level side effects we don't want to execute
+                // only to throw the result away).
+                if (isDuplicatePluginName(pluginName)) {
+                    continue;
+                }
                 const pluginFile = existsSync(pluginFileJs)
                     ? pluginFileJs
                     : pluginFileTs;
@@ -72,12 +229,16 @@ async function loadDefaultPlugins() {
                 logger.debug(`Loading default plugin from: ${pluginUrl}`);
                 const plugin = await import(__rewriteRelativeImportExtension(pluginUrl));
                 if (plugin.commands && typeof plugin.commands === "object") {
-                    loadedPlugins.set(pluginName, {
+                    const loaded = {
                         name: pluginName,
-                        commands: plugin.commands,
+                        version: pluginVersion,
+                        commands: { ...plugin.commands },
                         metadata: plugin.metadata || {},
-                    });
-                    const commandNames = Object.keys(plugin.commands);
+                    };
+                    validatePassthroughCommands(loaded);
+                    rejectDuplicateCommandNames(loaded);
+                    loadedPlugins.set(pluginName, loaded);
+                    const commandNames = Object.keys(loaded.commands);
                     logger.debug(`Successfully loaded default plugin: ${pluginName} with ${commandNames.length} commands:`, commandNames);
                 }
             }
@@ -108,7 +269,12 @@ export async function loadInstalledPlugins() {
         return;
     }
     try {
-        const entries = readdirSync(nodeModulesPath);
+        // Sort to make load order deterministic across filesystems/OSes.
+        // The first-registration-wins duplicate-name policy in
+        // `rejectDuplicateCommandNames` relies on this — without a stable
+        // sort, "who wins" would depend on `readdirSync()` order, which
+        // varies across platforms and filesystems.
+        const entries = readdirSync(nodeModulesPath).sort();
         logger.debug(`Scanning ${entries.length} entries in node_modules`);
         const packagesToScan = [];
         // Collect regular packages and scoped packages
@@ -117,10 +283,10 @@ export async function loadInstalledPlugins() {
                 continue;
             }
             if (entry.startsWith("@")) {
-                // Scoped package - scan subdirectories
+                // Scoped package - scan subdirectories (sorted for determinism).
                 const scopePath = join(nodeModulesPath, entry);
                 try {
-                    const scopedPackages = readdirSync(scopePath);
+                    const scopedPackages = readdirSync(scopePath).sort();
                     for (const scopedPkg of scopedPackages) {
                         if (!scopedPkg.startsWith(".")) {
                             packagesToScan.push(join(entry, scopedPkg));
@@ -136,6 +302,11 @@ export async function loadInstalledPlugins() {
                 packagesToScan.push(entry);
             }
         }
+        // Final defensive sort: `@scope/pkg` paths interleave with bare
+        // `pkg` paths in the order we appended them, but for
+        // duplicate-name resolution we want a single, stable lexicographic
+        // order over the full set.
+        packagesToScan.sort();
         logger.debug(`Found ${packagesToScan.length} packages to scan:`, packagesToScan);
         for (const packageName of packagesToScan) {
             const packagePath = join(nodeModulesPath, packageName);
@@ -165,18 +336,44 @@ export async function loadInstalledPlugins() {
                 const pluginFile = existsSync(pluginFileJs)
                     ? pluginFileJs
                     : pluginFileTs;
+                // Use the package.json#name (not the filesystem directory
+                // entry) as the canonical plugin name / loadedPlugins key.
+                // Under npm aliases (e.g. `npm i my-alias@npm:real-plugin`),
+                // the install directory is `my-alias` but the package name is
+                // `real-plugin`. Keying by directory would miss real
+                // duplicate-name collisions and surface the wrong name in
+                // duplicate warnings. `packageName` is kept for filesystem /
+                // logging purposes only.
+                const pluginName = typeof packageJson.name === "string" && packageJson.name.length > 0
+                    ? packageJson.name
+                    : packageName;
+                const pluginVersion = typeof packageJson.version === "string" &&
+                    packageJson.version.length > 0
+                    ? packageJson.version
+                    : "0.0.0";
+                // Check for duplicate plugin name BEFORE the dynamic import
+                // so a duplicate-name plugin's module code never runs (the
+                // import has top-level side effects we don't want to execute
+                // only to throw the result away).
+                if (isDuplicatePluginName(pluginName)) {
+                    continue;
+                }
                 // Use file:// protocol and add timestamp to bust cache
                 const pluginUrl = `file://${pluginFile}?t=${Date.now()}`;
                 logger.debug(`Loading plugin from: ${pluginUrl}`);
                 const plugin = await import(__rewriteRelativeImportExtension(pluginUrl));
                 if (plugin.commands && typeof plugin.commands === "object") {
-                    loadedPlugins.set(packageName, {
-                        name: packageName,
-                        commands: plugin.commands,
+                    const loaded = {
+                        name: pluginName,
+                        version: pluginVersion,
+                        commands: { ...plugin.commands },
                         metadata: plugin.metadata || {},
-                    });
-                    const commandNames = Object.keys(plugin.commands);
-                    logger.debug(`Successfully loaded plugin: ${packageName} with ${commandNames.length} commands:`, commandNames);
+                    };
+                    validatePassthroughCommands(loaded);
+                    rejectDuplicateCommandNames(loaded);
+                    loadedPlugins.set(pluginName, loaded);
+                    const commandNames = Object.keys(loaded.commands);
+                    logger.debug(`Successfully loaded plugin: ${pluginName} (dir: ${packageName}) with ${commandNames.length} commands:`, commandNames);
                 }
             }
             catch (error) {
@@ -200,16 +397,25 @@ export function getPluginCommands() {
     return allCommands;
 }
 /**
- * Execute a plugin command if it exists
+ * Execute a plugin command if it exists.
+ *
+ * `ctx` is the typed host context introduced in #377. When provided it
+ * is passed as the third handler argument; legacy two-argument
+ * handlers ignore it. When omitted the call site is treating the
+ * plugin as a fire-and-forget passthrough/help-render shim and
+ * intentionally does not construct a client.
  */
-export async function executePluginCommand(commandName, args, flags) {
+export async function executePluginCommand(commandName, args, flags, ctx) {
     const commands = getPluginCommands();
     const cmd = Object.hasOwn(commands, commandName)
         ? commands[commandName]
         : undefined;
     if (cmd) {
         if (typeof cmd === "function") {
-            if (flags !== undefined) {
+            if (ctx !== undefined) {
+                await cmd(args, flags, ctx);
+            }
+            else if (flags !== undefined) {
                 await cmd(args, flags);
             }
             else {
@@ -217,12 +423,25 @@ export async function executePluginCommand(commandName, args, flags) {
             }
         }
         else {
-            await cmd.handler(args, flags);
+            await cmd.handler(args, flags, ctx);
         }
         return true;
     }
     return false;
 }
+/**
+ * Look up the loaded version of a plugin by command name. Returns
+ * `undefined` if no plugin owns the command. Used by `--version` on a
+ * plugin verb to print the plugin's package version (#377).
+ */
+export function getPluginVersionForCommand(commandName) {
+    for (const plugin of loadedPlugins.values()) {
+        if (Object.hasOwn(plugin.commands, commandName)) {
+            return { pluginName: plugin.name, version: plugin.version };
+        }
+    }
+    return undefined;
+}
 /**
  * Check if a command is provided by a plugin
  */
@@ -240,21 +459,65 @@ export function getPluginCommandsInfo() {
     const infos = [];
     for (const plugin of loadedPlugins.values()) {
         for (const commandName of Object.keys(plugin.commands)) {
+            const meta = plugin.metadata?.commands?.[commandName];
+            const cmd = plugin.commands[commandName];
+            const flags = typeof cmd !== "function" ? cmd.flags : undefined;
             infos.push({
                 commandName,
                 pluginName: plugin.name,
-                description: plugin.metadata?.commands?.[commandName]?.description,
-                examples: plugin.metadata?.commands?.[commandName]?.examples,
-                subcommands: plugin.metadata?.commands?.[commandName]?.subcommands,
+                pluginVersion: plugin.version,
+                description: meta?.description,
+                helpDescription: meta?.helpDescription,
+                examples: meta?.examples,
+                subcommands: meta?.subcommands,
+                passthrough: meta?.passthrough === true ? true : undefined,
+                passthroughHint: meta?.passthroughHint,
+                flagsHint: meta?.flagsHint,
+                flags,
             });
         }
     }
     return infos;
 }
+/**
+ * True if the named command is a registered passthrough plugin command
+ * (#366). Used by the dispatcher to gate the strip-and-forward path.
+ */
+export function isPassthroughPluginCommand(commandName) {
+    for (const plugin of loadedPlugins.values()) {
+        if (!Object.hasOwn(plugin.commands, commandName))
+            continue;
+        const meta = plugin.metadata?.commands?.[commandName];
+        if (meta?.passthrough === true)
+            return true;
+    }
+    return false;
+}
 /**
  * Clear all loaded plugins (useful for testing and after uninstall)
  */
 export function clearLoadedPlugins() {
     loadedPlugins.clear();
+    pluginCollisions.length = 0;
+}
+/**
+ * Snapshot of plugin collisions detected at load time (#363). Returns
+ * a deep defensive copy of frozen records so callers cannot mutate
+ * the loader's bookkeeping (neither the array nor the entries).
+ * Order reflects the order in which the loader observed the
+ * collisions.
+ */
+export function getPluginCollisions() {
+    return Object.freeze(pluginCollisions.map((c) => Object.freeze({ ...c })));
+}
+export function getLoadedPluginSummaries() {
+    const summaries = [];
+    for (const plugin of loadedPlugins.values()) {
+        summaries.push({
+            name: plugin.name,
+            commands: Object.keys(plugin.commands),
+        });
+    }
+    return summaries;
 }
 //# sourceMappingURL=plugin-loader.js.map