@camunda8/cli 2.8.0-alpha.1 → 2.8.0-alpha.11

package/dist/open-helpers.js

@@ -0,0 +1,88 @@
+/**
+ * Pure helpers extracted from `src/commands/open.ts` so tests can import
+ * them without violating the test→commands import boundary (#291). The
+ * `openAppCommand` / `feedbackCommand` handlers in `src/commands/open.ts`
+ * re-import these.
+ */
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { requireOneOf, requirePositional } from "./command-validation.js";
+import { getLogger } from "./logger.js";
+export const OPEN_APPS = [
+    "operate",
+    "tasklist",
+    "modeler",
+    "optimize",
+];
+export function isAppName(value) {
+    // biome-ignore lint/plugin: safe widening — readonly tuple to readonly string[] for .includes() compatibility
+    return OPEN_APPS.includes(value);
+}
+/** Pattern that matches a self-managed REST API version suffix, e.g. `/v2` */
+const VERSION_SUFFIX_RE = /\/v\d+\/?$/;
+/**
+ * Derive the URL of a Camunda web application from the cluster base URL.
+ *
+ * Only supported for self-managed clusters where the base URL is the REST API
+ * endpoint (e.g. `http://localhost:8080/v2`). Returns `null` when the URL
+ * does not look like a self-managed gateway (no `/v<n>` suffix).
+ */
+export function deriveAppUrl(baseUrl, app) {
+    if (!VERSION_SUFFIX_RE.test(baseUrl)) {
+        return null;
+    }
+    const base = baseUrl.replace(VERSION_SUFFIX_RE, "").replace(/\/$/, "");
+    return `${base}/${app}`;
+}
+/**
+ * Determine the platform-appropriate command and arguments to open a URL.
+ *
+ * WSL is detected explicitly because it reports `linux`, but should use the
+ * Windows opener via interop rather than relying on `xdg-open`.
+ *
+ * Accepts optional overrides for testing.
+ */
+export function getBrowserCommand(url, plat = platform(), env = process.env) {
+    const isWsl = plat === "linux" && Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP);
+    if (plat === "darwin") {
+        return { command: "open", args: [url] };
+    }
+    if (plat === "win32" || isWsl) {
+        return { command: "cmd.exe", args: ["/c", "start", "", url] };
+    }
+    // Linux
+    return { command: "xdg-open", args: [url] };
+}
+/**
+ * Open a URL in the default system browser.
+ * Works on macOS, Linux, native Windows, and WSL.
+ */
+export function openUrl(url) {
+    const logger = getLogger();
+    const { command, args } = getBrowserCommand(url);
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", (error) => {
+        if (error.code === "ENOENT") {
+            logger.error(`Could not open the browser automatically because '${command}' is not available on PATH.`);
+            logger.info(`Open this URL manually: ${url}`);
+            return;
+        }
+        logger.error(`Could not open the browser automatically: ${error.message}`);
+        logger.info(`Open this URL manually: ${url}`);
+    });
+    child.unref();
+}
+const OPEN_USAGE = "Usage: c8 open <app> [--profile <name>]";
+/**
+ * Validate raw CLI positional + options for the open command.
+ * Returns a fully validated and type-narrowed input object.
+ * Exits with code 1 on invalid input.
+ */
+export function validateOpenAppOptions(app, options) {
+    return {
+        app: requireOneOf(requirePositional(app, "Application", OPEN_USAGE), OPEN_APPS, "application", OPEN_USAGE),
+        profile: options.profile,
+        dryRun: options.dryRun,
+    };
+}
+//# sourceMappingURL=open-helpers.js.map

package/dist/open-helpers.js.map

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

package/dist/plugin-loader.d.ts

@@ -1,8 +1,76 @@
 /**
  * Plugin loader for dynamic command loading
  */
+import type { FlagDef } from "./command-registry.ts";
+type CommandHandler = (args: string[], flags?: Record<string, unknown>) => Promise<void>;
+interface CommandWithFlags {
+    flags: Record<string, FlagDef>;
+    handler: CommandHandler;
+}
+type PluginCommand = CommandHandler | CommandWithFlags;
 interface PluginCommands {
-    [commandName: string]: (args: string[]) => Promise<void>;
+    [commandName: string]: PluginCommand;
+}
+/**
+ * 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
@@ -15,7 +83,7 @@ export declare function getPluginCommands(): PluginCommands;
 /**
  * Execute a plugin command if it exists
  */
-export declare function executePluginCommand(commandName: string, args: string[]): Promise<boolean>;
+export declare function executePluginCommand(commandName: string, args: string[], flags?: Record<string, unknown>): Promise<boolean>;
 /**
  * Check if a command is provided by a plugin
  */
@@ -31,6 +99,7 @@ export interface PluginCommandInfo {
     commandName: string;
     pluginName: string;
     description?: string;
+    helpDescription?: string;
     examples?: {
         command: string;
         description: string;
@@ -40,11 +109,42 @@ 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[];
 }
 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;
+/**
+ * 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[];
 export {};
 //# 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;AAQH,UAAU,cAAc;IACvB,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;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,GACZ,OAAO,CAAC,OAAO,CAAC,CASlB;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,13 @@ async function loadDefaultPlugins() {
                 // Read package.json
                 const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
                 const pluginName = packageJson.name || `default-${pluginDir}`;
+                // 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 +225,15 @@ 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,
+                        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 +264,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 +278,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 +297,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 +331,39 @@ 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;
+                // 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,
+                        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) {
@@ -193,7 +380,7 @@ export async function loadInstalledPlugins() {
  * Get all loaded plugin commands
  */
 export function getPluginCommands() {
-    const allCommands = {};
+    const allCommands = Object.create(null);
     for (const plugin of loadedPlugins.values()) {
         Object.assign(allCommands, plugin.commands);
     }
@@ -202,10 +389,23 @@ export function getPluginCommands() {
 /**
  * Execute a plugin command if it exists
  */
-export async function executePluginCommand(commandName, args) {
+export async function executePluginCommand(commandName, args, flags) {
     const commands = getPluginCommands();
-    if (commands[commandName]) {
-        await commands[commandName](args);
+    const cmd = Object.hasOwn(commands, commandName)
+        ? commands[commandName]
+        : undefined;
+    if (cmd) {
+        if (typeof cmd === "function") {
+            if (flags !== undefined) {
+                await cmd(args, flags);
+            }
+            else {
+                await cmd(args);
+            }
+        }
+        else {
+            await cmd.handler(args, flags);
+        }
         return true;
     }
     return false;
@@ -215,7 +415,7 @@ export async function executePluginCommand(commandName, args) {
  */
 export function isPluginCommand(commandName) {
     const commands = getPluginCommands();
-    return commandName in commands;
+    return Object.hasOwn(commands, commandName);
 }
 /**
  * Get list of all plugin command names
@@ -227,21 +427,61 @@ 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];
             infos.push({
                 commandName,
                 pluginName: plugin.name,
-                description: plugin.metadata?.commands?.[commandName]?.description,
-                examples: plugin.metadata?.commands?.[commandName]?.examples,
-                subcommands: plugin.metadata?.commands?.[commandName]?.subcommands,
+                description: meta?.description,
+                helpDescription: meta?.helpDescription,
+                examples: meta?.examples,
+                subcommands: meta?.subcommands,
+                passthrough: meta?.passthrough === true ? true : undefined,
+                passthroughHint: meta?.passthroughHint,
+                flagsHint: meta?.flagsHint,
             });
         }
     }
     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