feat: add id-based deduplication for plugins

Author: KurtGokhan

packages/padrone/src/command-utils.ts

@@ -287,6 +287,24 @@ export function errorResult(error: unknown, partial?: { command?: unknown; args?
   });
 }
 
+/**
+ * Deduplicates plugins by `id`. When multiple plugins share the same `id`,
+ * only the last one in the array is kept. Plugins without an `id` are always kept.
+ */
+function deduplicatePlugins(plugins: PadronePlugin<any, any>[]): PadronePlugin<any, any>[] {
+  // Fast path: no ids at all
+  if (!plugins.some((p) => p.id)) return plugins;
+
+  // Find the last index for each id
+  const lastIndex = new Map<string, number>();
+  for (let i = 0; i < plugins.length; i++) {
+    const id = plugins[i]!.id;
+    if (id) lastIndex.set(id, i);
+  }
+
+  return plugins.filter((p, i) => !p.id || lastIndex.get(p.id) === i);
+}
+
 /**
  * Runs a plugin chain for a given phase using the onion/middleware pattern.
  * Plugins are sorted by `order` (ascending, stable), then composed so that
@@ -299,8 +317,9 @@ export function runPluginChain<TCtx, TResult>(
   ctx: TCtx,
   core: () => TResult | Promise<TResult>,
 ): TResult | Promise<TResult> {
-  // Filter to plugins that have a handler for this phase, preserve insertion order
-  const phasePlugins = plugins.filter((p) => p[phase]);
+  // Deduplicate by id (last wins), then filter to plugins that have a handler for this phase
+  const deduped = deduplicatePlugins(plugins);
+  const phasePlugins = deduped.filter((p) => p[phase]);
   if (phasePlugins.length === 0) return core();
 
   // Stable sort by order (lower = outermost). Equal order preserves registration order.

packages/padrone/src/types.ts

@@ -1203,8 +1203,14 @@ type PluginPhaseHandler<TCtx, TNextResult, TReturn = TNextResult> = (
  * - Transform the return value of `next()` to alter outputs.
  */
 export type PadronePlugin<TArgs = unknown, TResult = unknown> = {
-  /** Unique name for this plugin. Used for identification and future disable/override support. */
+  /** Display name for this plugin. Used for identification in logs and debugging. */
   name: string;
+  /**
+   * Optional unique identifier for deduplication. When multiple plugins share the same `id`,
+   * only the last one registered is kept. Useful for allowing downstream code to override
+   * a plugin without accumulating duplicates.
+   */
+  id?: string;
   /**
    * Ordering hint. Lower values run as outer layers (earlier before `next()`, later after).
    * Plugins with the same order preserve registration order. Defaults to `0`.

packages/padrone/tests/plugin.test.ts

@@ -1094,4 +1094,155 @@ describe('plugins', () => {
       expect(log).toEqual(['root', 'db', 'migrate']);
     });
   });
+
+  describe('id deduplication', () => {
+    it('should keep the last plugin when multiple share the same id', () => {
+      const log: string[] = [];
+
+      const program = makeProgram()
+        .use({
+          name: 'first',
+          id: 'auth',
+          execute: (_ctx, next) => {
+            log.push('first');
+            return next();
+          },
+        })
+        .use({
+          name: 'second',
+          id: 'auth',
+          execute: (_ctx, next) => {
+            log.push('second');
+            return next();
+          },
+        });
+
+      program.eval('greet World');
+      expect(log).toEqual(['second']);
+    });
+
+    it('should not affect plugins without an id', () => {
+      const log: string[] = [];
+
+      const program = makeProgram()
+        .use({
+          name: 'a',
+          execute: (_ctx, next) => {
+            log.push('a');
+            return next();
+          },
+        })
+        .use({
+          name: 'b',
+          execute: (_ctx, next) => {
+            log.push('b');
+            return next();
+          },
+        });
+
+      program.eval('greet World');
+      expect(log).toEqual(['a', 'b']);
+    });
+
+    it('should mix plugins with and without ids correctly', () => {
+      const log: string[] = [];
+
+      const program = makeProgram()
+        .use({
+          name: 'no-id-1',
+          execute: (_ctx, next) => {
+            log.push('no-id-1');
+            return next();
+          },
+        })
+        .use({
+          name: 'first-auth',
+          id: 'auth',
+          execute: (_ctx, next) => {
+            log.push('first-auth');
+            return next();
+          },
+        })
+        .use({
+          name: 'no-id-2',
+          execute: (_ctx, next) => {
+            log.push('no-id-2');
+            return next();
+          },
+        })
+        .use({
+          name: 'second-auth',
+          id: 'auth',
+          execute: (_ctx, next) => {
+            log.push('second-auth');
+            return next();
+          },
+        });
+
+      program.eval('greet World');
+      expect(log).toEqual(['no-id-1', 'no-id-2', 'second-auth']);
+    });
+
+    it('should deduplicate across parent chain (subcommand overrides parent)', () => {
+      const log: string[] = [];
+
+      const program = createPadrone('test')
+        .command('greet', (c) =>
+          c
+            .arguments(z.object({ name: z.string() }), { positional: ['name'] })
+            .action((args) => `Hello, ${args.name}!`)
+            .use({
+              name: 'sub-auth',
+              id: 'auth',
+              execute: (_ctx, next) => {
+                log.push('sub-auth');
+                return next();
+              },
+            }),
+        )
+        .use({
+          name: 'root-auth',
+          id: 'auth',
+          execute: (_ctx, next) => {
+            log.push('root-auth');
+            return next();
+          },
+        });
+
+      program.eval('greet World');
+      // Subcommand plugin comes after root in collected chain, so it wins
+      expect(log).toEqual(['sub-auth']);
+    });
+
+    it('should deduplicate per phase independently', () => {
+      const log: string[] = [];
+
+      const program = makeProgram()
+        .use({
+          name: 'first',
+          id: 'logger',
+          validate: (_ctx, next) => {
+            log.push('validate:first');
+            return next();
+          },
+          execute: (_ctx, next) => {
+            log.push('execute:first');
+            return next();
+          },
+        })
+        .use({
+          name: 'second',
+          id: 'logger',
+          execute: (_ctx, next) => {
+            log.push('execute:second');
+            return next();
+          },
+          // no validate — but dedup still removes the first plugin entirely
+        });
+
+      program.eval('greet World');
+      // The second plugin replaced the first (same id), so first's validate is gone too
+      expect(log).toEqual(['execute:second']);
+    });
+  });
 });