feat: add plugins system

playground/cli.ts

@@ -1,4 +1,5 @@
 import { defineCommand, runMain } from "../src";
+import logPlugin from "./plugins/log";
 
 const main = defineCommand({
   meta: {
@@ -12,6 +13,7 @@
   cleanup() {
     console.log("Cleanup");
   },
+  plugins: [logPlugin],
   subCommands: {
     build: () => import("./commands/build").then((r) => r.default),
     deploy: () => import("./commands/deploy").then((r) => r.default),

playground/commands/debug.ts

@@ -1,11 +1,21 @@
 import consola from "consola";
-import { defineCommand } from "../../src";
+import { defineCittyPlugin, defineCommand } from "../../src";
+
+const buildPlugin = defineCittyPlugin({
+  name: "build",
+  setup() {
+    consola.info("Setting up build plugin");
+  },
+  cleanup() {
+    consola.info("Cleaning up build plugin");
+  },
+});
 
 export default defineCommand({
   meta: {
     name: "debug",
     description: "Debug the project",
-    hidden: true
+    hidden: true,
   },
   args: {
     verbose: {
@@ -18,6 +28,7 @@
       description: "Only debug a specific function",
     },
   },
+  plugins: [buildPlugin],
   run({ args }) {
     consola.log("Debug");
     consola.log("Parsed args:", args);

playground/hello.ts

@@ -1,5 +1,6 @@
 import consola from "consola";
 import { defineCommand, createMain } from "../src";
+import logPlugin from "./plugins/log";
 
 const command = defineCommand({
   meta: {
@@ -30,6 +31,7 @@
       required: false,
     },
   },
+  plugins: [logPlugin],
   run({ args }) {
     consola.log(args);
     const msg = [

playground/plugins/log.ts

@@ -0,0 +1,16 @@
+import consola from "consola";
+import { defineCittyPlugin } from "../../src";
+
+export default defineCittyPlugin(() => {
+  consola.success("Log plugin loaded");
+
+  return {
+    name: "log",
+    setup() {
+      consola.info("Setting up log plugin");
+    },
+    cleanup() {
+      consola.info("Cleaning up log plugin");
+    },
+  };
+});

src/command.ts

@@ -1,6 +1,7 @@
 import type { CommandContext, CommandDef, ArgsDef } from "./types";
 import { CLIError, resolveValue } from "./_utils";
 import { parseArgs } from "./args";
+import { resolvePlugins } from "./plugin";
 
 export function defineCommand<T extends ArgsDef = ArgsDef>(
   def: CommandDef<T>,
@@ -28,6 +29,16 @@ export async function runCommand<T extends ArgsDef = ArgsDef>(
     cmd,
   };
 
+  const plugins = await resolvePlugins(cmd.plugins ?? []);
+
+  // Apply setup hooks from plugins
+  for (const plugin of plugins) {
+    if (typeof plugin.setup === "function") {
+      // TODO: Pass plugin context?
+      await plugin.setup();
+    }
+  }
+
   // Setup hook
   if (typeof cmd.setup === "function") {
     await cmd.setup(context);
@@ -68,6 +79,13 @@ export async function runCommand<T extends ArgsDef = ArgsDef>(
     if (typeof cmd.cleanup === "function") {
       await cmd.cleanup(context);
     }
+    // Apply cleanup hooks from plugins
+    for (const plugin of plugins) {
+      if (typeof plugin.cleanup === "function") {
+        // TODO: Pass plugin context?
+        await plugin.cleanup();
+      }
+    }
   }
   return { result };
 }

src/index.ts

@@ -6,3 +6,4 @@ export { defineCommand, runCommand } from "./command";
 export { parseArgs } from "./args";
 export { renderUsage, showUsage } from "./usage";
 export { runMain, createMain } from "./main";
+export { defineCittyPlugin } from "./plugin";

src/plugin.ts

@@ -0,0 +1,41 @@
+import { CittyPlugin, Resolvable } from "./types";
+
+/**
+ * Define a Citty plugin.
+ *
+ * Can be a function that returns a plugin object or a plugin object.
+ *
+ * @example
+ * ```ts
+ * import { defineCittyPlugin } from "citty";
+ *
+ * export const myPlugin = defineCittyPlugin({
+ *   name: "my-plugin",
+ *   async setup() {
+ *     console.log("Setting up my plugin");
+ *   },
+ *   async cleanup() {
+ *    console.log("Cleaning up my plugin");
+ *   },
+ * });
+ * ```
+ */
+export function defineCittyPlugin(
+  plugin: Resolvable<CittyPlugin>,
+): Resolvable<CittyPlugin> {
+  return plugin;
+}
+
+/**
+ * Resolve a Citty plugin since it can be a function that returns a plugin object.
+ */
+export const resolvePlugin = async (plugin: Resolvable<CittyPlugin>) => {
+  return typeof plugin === "function" ? await plugin() : plugin;
+};
+
+/**
+ * Resolve an array of Citty plugins.
+ */
+export const resolvePlugins = (plugins: Resolvable<CittyPlugin>[]) => {
+  return Promise.all(plugins.map((plugin) => resolvePlugin(plugin)));
+};

src/types.ts

@@ -94,6 +94,7 @@ export type CommandDef<T extends ArgsDef = ArgsDef> = {
   setup?: (context: CommandContext<T>) => any | Promise<any>;
   cleanup?: (context: CommandContext<T>) => any | Promise<any>;
   run?: (context: CommandContext<T>) => any | Promise<any>;
+  plugins?: Resolvable<CittyPlugin>[];
 };
 
 export type CommandContext<T extends ArgsDef = ArgsDef> = {
@@ -104,6 +105,14 @@ export type CommandContext<T extends ArgsDef = ArgsDef> = {
   data?: any;
 };
 
+// ----- Plugin -----
+
+export type CittyPlugin = {
+  name: string;
+  setup?(): Promise<void> | void;
+  cleanup?(): Promise<void> | void;
+};
+
 // ----- Utils -----
 
 export type Awaitable<T> = () => T | Promise<T>;