@holo-js/cli 0.2.5 → 0.3.0

package/dist/index.mjs

@@ -17,24 +17,30 @@ import {
   splitCsv
 } from "./chunk-VRGB6DIS.mjs";
 import {
-  hasProjectDependency
-} from "./chunk-FGQ2I2YH.mjs";
+  hasProjectDependency,
+  pinProjectDependencyVersions,
+  removeProjectDependency,
+  upsertProjectDependency
+} from "./chunk-LHK5YUR4.mjs";
 import {
   fileExists
-} from "./chunk-LBJAJLKU.mjs";
+} from "./chunk-M3IPUCTM.mjs";
 import {
   runWithSpinner,
   supportsSpinner,
   writeLine
 } from "./chunk-I7QBCEV7.mjs";
-import "./chunk-D7O4SU6N.mjs";
-import "./chunk-VP2E62DF.mjs";
-import "./chunk-TWITVSFZ.mjs";
-import "./chunk-YEFJBN56.mjs";
-import "./chunk-J76GH2DR.mjs";
+import "./chunk-HX6MOYBO.mjs";
+import "./chunk-6BHJLCAO.mjs";
+import "./chunk-JVLZ3SOW.mjs";
+import "./chunk-QSVMXMTQ.mjs";
+import "./chunk-R4ZYMEDU.mjs";
+import "./chunk-3RFRE7XG.mjs";
+import "./chunk-TRYHX5S4.mjs";
 import {
+  APP_CONFIG_FILE_NAMES,
   SUPPORTED_AUTH_SOCIAL_PROVIDERS
-} from "./chunk-ILU426CF.mjs";
+} from "./chunk-YACY2572.mjs";
 
 // src/types.ts
 function defineCommand(command) {
@@ -42,6 +48,8 @@ function defineCommand(command) {
 }
 
 // src/cli.ts
+import { cp, mkdtemp, readFile as readFile2, rm, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
 import { resolve as resolve2 } from "path";
 import { clearConfigCache, resolveConfigCachePath } from "@holo-js/config";
 
@@ -111,12 +119,7 @@ async function generateProjectAppKey(projectRoot) {
   };
 }
 
-// src/cli.ts
-var AUTH_INSTALL_FEATURES = ["social", "workos", "clerk"];
-var AUTH_SOCIAL_PROVIDER_MODES = ["default", "specific"];
-var EVENTS_QUEUE_ACTIONS = ["skip", "enable"];
-var MODEL_GENERATOR_OPTIONS = ["migration", "observer", "seeder", "factory"];
-var COMMAND_LIST_DESCRIPTION_COLUMN = 32;
+// src/command-executors.ts
 var runtimeModulePromise;
 var queueModulePromise;
 var cacheModulePromise;
@@ -129,127 +132,110 @@ var securityModulePromise;
 var devModulePromise;
 var projectConfigModulePromise;
 var projectDiscoveryModulePromise;
+var projectPluginsModulePromise;
 var projectRuntimeModulePromise;
 var projectScaffoldModulePromise;
 var agentSkillsModulePromise;
 function loadRuntimeModule() {
-  runtimeModulePromise ??= import("./runtime-M3G5OKQV.mjs");
+  runtimeModulePromise ??= import("./runtime-4TJYZLQV.mjs");
   return runtimeModulePromise;
 }
-function loadQueueModule() {
-  queueModulePromise ??= import("./queue-O3OSLGOV.mjs");
-  return queueModulePromise;
-}
-function loadCacheModule() {
-  cacheModulePromise ??= import("./cache-KVRYC7FB.mjs");
-  return cacheModulePromise;
-}
-function loadQueueMigrationsModule() {
-  queueMigrationsModulePromise ??= import("./queue-migrations-7T42S4FX.mjs");
-  return queueMigrationsModulePromise;
-}
-function loadCacheMigrationsModule() {
-  cacheMigrationsModulePromise ??= import("./cache-migrations-APDFSFEX.mjs");
-  return cacheMigrationsModulePromise;
-}
-function loadMediaMigrationsModule() {
-  mediaMigrationsModulePromise ??= import("./media-migrations-IWCSCKSA.mjs");
-  return mediaMigrationsModulePromise;
-}
-function loadGeneratorsModule() {
-  generatorsModulePromise ??= import("./generators-WQHI7DBW.mjs");
-  return generatorsModulePromise;
-}
-function loadBroadcastModule() {
-  broadcastModulePromise ??= import("./broadcast-5MJ3GJK7.mjs");
-  return broadcastModulePromise;
-}
 function loadSecurityModule() {
-  securityModulePromise ??= import("./security-ST6ED7EK.mjs");
+  securityModulePromise ??= import("./security-KYTLP4DF.mjs");
   return securityModulePromise;
 }
-function loadDevModule() {
-  devModulePromise ??= import("./dev-CT4DRTLN.mjs");
-  return devModulePromise;
-}
 function loadProjectConfigModule() {
-  projectConfigModulePromise ??= import("./config-MD27U4FM.mjs");
+  projectConfigModulePromise ??= import("./config-BZHQK532.mjs");
   return projectConfigModulePromise;
 }
 function loadProjectDiscoveryModule() {
-  projectDiscoveryModulePromise ??= import("./discovery-GWTBF5RZ.mjs");
+  projectDiscoveryModulePromise ??= import("./discovery-HNH3BLDL.mjs");
   return projectDiscoveryModulePromise;
 }
+function loadProjectPluginsModule() {
+  projectPluginsModulePromise ??= import("./plugins-ZGLB6JO6.mjs");
+  return projectPluginsModulePromise;
+}
 function loadProjectRuntimeModule() {
-  projectRuntimeModulePromise ??= import("./runtime-GSXF4NB3.mjs");
+  projectRuntimeModulePromise ??= import("./runtime-VR5BDPYQ.mjs");
   return projectRuntimeModulePromise;
 }
 function loadProjectScaffoldModule() {
-  projectScaffoldModulePromise ??= import("./scaffold-5BOVJYF3.mjs");
+  projectScaffoldModulePromise ??= import("./scaffold-ASEX5LEX.mjs");
   return projectScaffoldModulePromise;
 }
 function loadAgentSkillsModule() {
-  agentSkillsModulePromise ??= import("./agent-skills-MSEMQUXT.mjs");
+  agentSkillsModulePromise ??= import("./agent-skills-CHAXS2YN.mjs");
   return agentSkillsModulePromise;
 }
 async function resolveRuntimeExecutor(runtimeExecutor) {
-  return runtimeExecutor ?? (await loadRuntimeModule()).withRuntimeEnvironment;
+  runtimeModulePromise ??= import("./runtime-4TJYZLQV.mjs");
+  return runtimeExecutor ?? (await runtimeModulePromise).withRuntimeEnvironment;
 }
-var projectExecutorLoaders = {
-  runProjectPrepare: async () => (await loadDevModule()).runProjectPrepare,
-  runProjectDevServer: async () => (await loadDevModule()).runProjectDevServer,
-  runProjectBuild: async () => (await loadDevModule()).runProjectBuild,
-  runProjectStartServer: async () => (await loadDevModule()).runProjectStartServer,
-  runProjectDependencyInstall: async () => (await loadDevModule()).runProjectDependencyInstall
-};
-async function resolveExecutor(executors, loaders, key) {
+async function resolveExecutor(executors, loader, key) {
   const existing = executors[key];
-  if (existing) {
-    return existing;
-  }
-  return await loaders[key]();
+  return existing ? existing : await loader();
 }
-async function resolveProjectExecutor(projectExecutors, key) {
-  return await resolveExecutor(projectExecutors, projectExecutorLoaders, key);
+async function resolveProjectExecutor(executors, key) {
+  devModulePromise ??= import("./dev-GQT37XJU.mjs");
+  return resolveExecutor(executors, async () => (await devModulePromise)[key], key);
 }
-var queueExecutorLoaders = {
-  runQueueFailedTableCommand: async () => (await loadQueueMigrationsModule()).runQueueFailedTableCommand,
-  runQueueTableCommand: async () => (await loadQueueMigrationsModule()).runQueueTableCommand,
-  runQueueFailedCommand: async () => (await loadQueueModule()).runQueueFailedCommand,
-  runQueueFlushCommand: async () => (await loadQueueModule()).runQueueFlushCommand,
-  runQueueWorkCommand: async () => (await loadQueueModule()).runQueueWorkCommand,
-  runQueueForgetCommand: async () => (await loadQueueModule()).runQueueForgetCommand,
-  runQueueListen: async () => (await loadQueueModule()).runQueueListen,
-  runQueueRestartCommand: async () => (await loadQueueModule()).runQueueRestartCommand,
-  runQueueRetryCommand: async () => (await loadQueueModule()).runQueueRetryCommand,
-  runQueueClearCommand: async () => (await loadQueueModule()).runQueueClearCommand
-};
-var cacheExecutorLoaders = {
-  runCacheTableCommand: async () => (await loadCacheMigrationsModule()).runCacheTableCommand,
-  runCacheClearCommand: async () => (await loadCacheModule()).runCacheClearCommand,
-  runCacheForgetCommand: async () => (await loadCacheModule()).runCacheForgetCommand
-};
-var mediaExecutorLoaders = {
-  runMediaTableCommand: async () => (await loadMediaMigrationsModule()).runMediaTableCommand
-};
-var broadcastExecutorLoaders = {
-  runBroadcastWorkCommand: async () => (await loadBroadcastModule()).runBroadcastWorkCommand
-};
-async function resolveQueueExecutor(queueExecutors, key) {
-  return await resolveExecutor(queueExecutors, queueExecutorLoaders, key);
+async function resolveQueueExecutor(executors, key) {
+  return resolveExecutor(executors, async () => {
+    if (key === "runQueueFailedTableCommand" || key === "runQueueTableCommand") {
+      queueMigrationsModulePromise ??= import("./queue-migrations-U477YSFD.mjs");
+      const migrations = await queueMigrationsModulePromise;
+      return key === "runQueueFailedTableCommand" ? migrations.runQueueFailedTableCommand : migrations.runQueueTableCommand;
+    }
+    queueModulePromise ??= import("./queue-BEZDCZCY.mjs");
+    const queue = await queueModulePromise;
+    const resolved = {
+      runQueueFailedCommand: queue.runQueueFailedCommand,
+      runQueueFlushCommand: queue.runQueueFlushCommand,
+      runQueueWorkCommand: queue.runQueueWorkCommand,
+      runQueueForgetCommand: queue.runQueueForgetCommand,
+      runQueueListen: queue.runQueueListen,
+      runQueueRestartCommand: queue.runQueueRestartCommand,
+      runQueueRetryCommand: queue.runQueueRetryCommand,
+      runQueueClearCommand: queue.runQueueClearCommand
+    };
+    return resolved[key];
+  }, key);
 }
-async function resolveCacheExecutor(cacheExecutors, key) {
-  return await resolveExecutor(cacheExecutors, cacheExecutorLoaders, key);
+async function resolveCacheExecutor(executors, key) {
+  return resolveExecutor(executors, async () => {
+    if (key === "runCacheTableCommand") {
+      cacheMigrationsModulePromise ??= import("./cache-migrations-PD2T5AV4.mjs");
+      return (await cacheMigrationsModulePromise).runCacheTableCommand;
+    }
+    cacheModulePromise ??= import("./cache-DUVBBOZU.mjs");
+    const cache = await cacheModulePromise;
+    const resolved = {
+      runCacheClearCommand: cache.runCacheClearCommand,
+      runCacheForgetCommand: cache.runCacheForgetCommand
+    };
+    return resolved[key];
+  }, key);
 }
-async function resolveMediaExecutor(mediaExecutors, key) {
-  return await resolveExecutor(mediaExecutors, mediaExecutorLoaders, key);
+async function resolveMediaExecutor(executors, key) {
+  mediaMigrationsModulePromise ??= import("./media-migrations-EG34NYAG.mjs");
+  return resolveExecutor(executors, async () => (await mediaMigrationsModulePromise)[key], key);
 }
-async function resolveBroadcastExecutor(broadcastExecutors, key) {
-  return await resolveExecutor(broadcastExecutors, broadcastExecutorLoaders, key);
+async function resolveBroadcastExecutor(executors, key) {
+  broadcastModulePromise ??= import("./broadcast-5VZM5SGQ.mjs");
+  return resolveExecutor(executors, async () => (await broadcastModulePromise)[key], key);
 }
 async function resolveGeneratorCommand(key) {
-  return (await loadGeneratorsModule())[key];
+  generatorsModulePromise ??= import("./generators-3FVW4AEJ.mjs");
+  return (await generatorsModulePromise)[key];
 }
+
+// src/cli.ts
+var AUTH_INSTALL_FEATURES = ["social", "workos", "clerk"];
+var AUTH_SOCIAL_PROVIDER_MODES = ["default", "specific"];
+var EVENTS_QUEUE_ACTIONS = ["skip", "enable"];
+var MODEL_GENERATOR_OPTIONS = ["migration", "observer", "seeder", "factory"];
+var COMMAND_LIST_DESCRIPTION_COLUMN = 32;
 function createCommandContext(io, projectRoot, loadProject, input) {
   return {
     cwd: io.cwd,
@@ -259,6 +245,23 @@ function createCommandContext(io, projectRoot, loadProject, input) {
     loadProject
   };
 }
+function serializePassthroughInput(input) {
+  const tokens = [...input.args];
+  for (const [name, value] of Object.entries(input.flags)) {
+    if (value === false) {
+      continue;
+    }
+    const flag = name.length === 1 ? `-${name}` : `--${name}`;
+    const values = Array.isArray(value) ? value : [value];
+    for (const currentValue of values) {
+      tokens.push(flag);
+      if (currentValue !== true) {
+        tokens.push(String(currentValue));
+      }
+    }
+  }
+  return tokens;
+}
 function printCommandList(io, registry) {
   const internal = registry.filter((command) => command.source === "internal");
   const app = registry.filter((command) => command.source === "app");
@@ -314,6 +317,130 @@ async function runProjectDependencyInstallForProject(context, projectExecutors,
     writeLine(context.stdout, "  - installed dependencies");
   }
 }
+function formatPluginLabel(plugin) {
+  return plugin.name ? `${plugin.name} (${plugin.id})` : plugin.id;
+}
+function formatPluginContributionLines(plugin) {
+  const contributes = plugin.contributes;
+  if (!contributes) {
+    return [];
+  }
+  const lines = [];
+  if (contributes.framework) {
+    lines.push(`framework: ${contributes.framework.displayName}`);
+  }
+  if (contributes.dependencies?.holo?.length) {
+    lines.push(`holo packages: ${contributes.dependencies.holo.join(", ")}`);
+  }
+  if (contributes.dependencies?.runtime?.length) {
+    lines.push(`runtime packages: ${contributes.dependencies.runtime.join(", ")}`);
+  }
+  if (contributes.config?.files?.length) {
+    lines.push(`config files: ${contributes.config.files.join(", ")}`);
+  }
+  if (contributes.config?.env?.length) {
+    lines.push(`env keys: ${contributes.config.env.join(", ")}`);
+  }
+  if (contributes.broadcast?.drivers) {
+    const driverNames = Object.keys(contributes.broadcast.drivers);
+    if (driverNames.length > 0) {
+      lines.push(`broadcast drivers: ${driverNames.join(", ")}`);
+    }
+  }
+  if (contributes.cache?.drivers) {
+    const driverNames = Object.keys(contributes.cache.drivers);
+    if (driverNames.length > 0) {
+      lines.push(`cache drivers: ${driverNames.join(", ")}`);
+    }
+  }
+  if (contributes.queue?.drivers) {
+    const driverNames = Object.keys(contributes.queue.drivers);
+    if (driverNames.length > 0) {
+      lines.push(`queue drivers: ${driverNames.join(", ")}`);
+    }
+  }
+  if (contributes.mail?.drivers) {
+    const driverNames = Object.keys(contributes.mail.drivers);
+    if (driverNames.length > 0) {
+      lines.push(`mail drivers: ${driverNames.join(", ")}`);
+    }
+  }
+  if (contributes.notifications?.channels) {
+    const channelNames = Object.keys(contributes.notifications.channels);
+    if (channelNames.length > 0) {
+      lines.push(`notification channels: ${channelNames.join(", ")}`);
+    }
+  }
+  if (contributes.runtime?.boot) {
+    lines.push(`runtime boot: ${contributes.runtime.boot}`);
+  }
+  if (contributes.cli?.commands) {
+    lines.push(`cli commands: ${contributes.cli.commands}`);
+  }
+  if (contributes.migrations?.publish) {
+    lines.push(`migration publisher: ${contributes.migrations.publish}`);
+  }
+  return lines;
+}
+function writePluginDetails(context, loadedPlugin) {
+  writeLine(context.stdout, `Plugin: ${formatPluginLabel(loadedPlugin.definition)}`);
+  writeLine(context.stdout, `  - package: ${loadedPlugin.packageName}`);
+  if (loadedPlugin.definition.description) {
+    writeLine(context.stdout, `  - description: ${loadedPlugin.definition.description}`);
+  }
+  const contributionLines = formatPluginContributionLines(loadedPlugin.definition);
+  if (contributionLines.length === 0) {
+    writeLine(context.stdout, "  - contributions: none");
+    return;
+  }
+  for (const line of contributionLines) {
+    writeLine(context.stdout, `  - ${line}`);
+  }
+}
+async function readPackageJsonSnapshot(projectRoot) {
+  return await readFile2(resolve2(projectRoot, "package.json"), "utf8");
+}
+async function restorePackageJsonSnapshot(projectRoot, snapshot) {
+  await writeFile2(resolve2(projectRoot, "package.json"), snapshot);
+}
+async function readAppConfigSnapshot(projectRoot) {
+  for (const fileName of APP_CONFIG_FILE_NAMES) {
+    const path = resolve2(projectRoot, fileName);
+    if (await fileExists(path)) {
+      return {
+        path,
+        contents: await readFile2(path, "utf8")
+      };
+    }
+  }
+  return void 0;
+}
+async function restoreAppConfigSnapshot(snapshot) {
+  if (!snapshot) {
+    return;
+  }
+  await writeFile2(snapshot.path, snapshot.contents);
+}
+async function readDirectorySnapshot(projectRoot, relativePath) {
+  const path = resolve2(projectRoot, relativePath);
+  if (!await fileExists(path)) {
+    return { path };
+  }
+  const snapshotPath = await mkdtemp(resolve2(tmpdir(), "holo-cli-plugin-add-"));
+  await cp(path, snapshotPath, { recursive: true, force: true });
+  return { path, snapshotPath };
+}
+async function restoreDirectorySnapshot(snapshot) {
+  await rm(snapshot.path, { recursive: true, force: true });
+  if (snapshot.snapshotPath) {
+    await cp(snapshot.snapshotPath, snapshot.path, { recursive: true, force: true });
+  }
+}
+async function cleanupDirectorySnapshot(snapshot) {
+  if (snapshot.snapshotPath) {
+    await rm(snapshot.snapshotPath, { recursive: true, force: true });
+  }
+}
 function createInternalCommands(context, runtimeExecutor, queueExecutors = {}, projectExecutors = {}, broadcastExecutors = {}, securityExecutors = {}, cacheExecutors = {}, mediaExecutors = {}) {
   return [
     {
@@ -738,6 +865,196 @@ function createInternalCommands(context, runtimeExecutor, queueExecutors = {}, p
         await runProjectDependencyInstallAfterPackageJsonUpdate(context, projectExecutors, result.updatedPackageJson);
       }
     },
+    {
+      name: "plugin:add",
+      aliases: ["plugins:add"],
+      description: "Install and activate a Holo plugin package.",
+      usage: "holo plugin:add <package>",
+      source: "internal",
+      async prepare(input) {
+        const packageName = await ensureRequiredArg(context, input, 0, "Plugin package");
+        return { args: [packageName], flags: {} };
+      },
+      async run(commandContext) {
+        const packageName = String(commandContext.args[0] ?? "");
+        const plugins = await loadProjectPluginsModule();
+        const packageJsonSnapshot = await readPackageJsonSnapshot(context.projectRoot);
+        const appConfigSnapshot = await readAppConfigSnapshot(context.projectRoot);
+        const holoDirectorySnapshot = await readDirectorySnapshot(context.projectRoot, ".holo-js");
+        let dependencyInstallSucceeded = false;
+        let updatedDependencies = false;
+        let updatedPackageJson = false;
+        let loadedPlugin;
+        let contributedDependencies = [];
+        let updatedContributedDependencies = false;
+        let activated = false;
+        try {
+          updatedPackageJson = await upsertProjectDependency(context.projectRoot, packageName);
+          updatedDependencies = updatedPackageJson || updatedDependencies;
+          if (updatedPackageJson) {
+            await runProjectDependencyInstallForProject(context, projectExecutors, context.projectRoot);
+            dependencyInstallSucceeded = true;
+            await pinProjectDependencyVersions(context.projectRoot, [packageName]);
+          }
+          loadedPlugin = await plugins.loadHoloPluginFromPackage(context.projectRoot, packageName);
+          contributedDependencies = [
+            ...loadedPlugin.definition.contributes?.dependencies?.holo ?? [],
+            ...loadedPlugin.definition.contributes?.dependencies?.runtime ?? []
+          ];
+          for (const dependencyName of contributedDependencies) {
+            const updatedContributedDependency = await upsertProjectDependency(context.projectRoot, dependencyName);
+            updatedContributedDependencies = updatedContributedDependency || updatedContributedDependencies;
+          }
+          updatedDependencies = updatedContributedDependencies || updatedDependencies;
+          if (updatedContributedDependencies) {
+            await runProjectDependencyInstallForProject(context, projectExecutors, context.projectRoot);
+            dependencyInstallSucceeded = true;
+            await pinProjectDependencyVersions(context.projectRoot, contributedDependencies);
+          }
+          activated = await plugins.activateProjectPlugin(context.projectRoot, packageName);
+          if (activated) {
+            const runProjectPrepare = await resolveProjectExecutor(projectExecutors, "runProjectPrepare");
+            await runProjectPrepare(context.projectRoot, context);
+          }
+        } catch (error) {
+          await restoreAppConfigSnapshot(appConfigSnapshot);
+          await restorePackageJsonSnapshot(context.projectRoot, packageJsonSnapshot);
+          await restoreDirectorySnapshot(holoDirectorySnapshot);
+          if (updatedDependencies && dependencyInstallSucceeded) {
+            await runProjectDependencyInstallForProject(context, projectExecutors, context.projectRoot).catch(() => void 0);
+          }
+          await cleanupDirectorySnapshot(holoDirectorySnapshot);
+          throw error;
+        }
+        writeLine(context.stdout, `Installed Holo plugin: ${formatPluginLabel(loadedPlugin.definition)}`);
+        writeLine(context.stdout, `  - package: ${updatedPackageJson ? "added" : "already present"} ${packageName}`);
+        if (contributedDependencies.length > 0) {
+          writeLine(
+            context.stdout,
+            `  - dependencies: ${updatedContributedDependencies ? "updated" : "already present"} ${contributedDependencies.join(", ")}`
+          );
+        }
+        writeLine(context.stdout, `  - activation: ${activated ? "updated config/app.ts" : "already active"}`);
+        if (activated) {
+          writeLine(context.stdout, "  - refreshed generated artifacts");
+        }
+        for (const line of formatPluginContributionLines(loadedPlugin.definition)) {
+          writeLine(context.stdout, `  - ${line}`);
+        }
+        await cleanupDirectorySnapshot(holoDirectorySnapshot);
+      }
+    },
+    {
+      name: "plugin:list",
+      aliases: ["plugins:list"],
+      description: "List active Holo plugins.",
+      usage: "holo plugin:list",
+      source: "internal",
+      async prepare() {
+        return { args: [], flags: {} };
+      },
+      async run() {
+        const plugins = await loadProjectPluginsModule();
+        const resolvedPlugins = await plugins.resolveProjectPlugins(context.projectRoot);
+        writeLine(context.stdout, "Active Holo plugins:");
+        if (resolvedPlugins.length === 0) {
+          writeLine(context.stdout, "  (none)");
+          return;
+        }
+        for (const resolvedPlugin of resolvedPlugins) {
+          if (resolvedPlugin.loaded) {
+            writeLine(context.stdout, `  - ${resolvedPlugin.packageName}: ${formatPluginLabel(resolvedPlugin.loaded.definition)}`);
+            continue;
+          }
+          writeLine(context.stdout, `  - ${resolvedPlugin.packageName}: failed`);
+          if (resolvedPlugin.error) {
+            writeLine(context.stdout, `    ${resolvedPlugin.error}`);
+          }
+        }
+      }
+    },
+    {
+      name: "plugin:remove",
+      aliases: ["plugins:remove"],
+      description: "Deactivate a Holo plugin package.",
+      usage: "holo plugin:remove <package> [--uninstall]",
+      source: "internal",
+      async prepare(input) {
+        const packageName = await ensureRequiredArg(context, input, 0, "Plugin package");
+        return {
+          args: [packageName],
+          flags: {
+            ...resolveBooleanFlag(input.flags, "uninstall") === true ? { uninstall: true } : {}
+          }
+        };
+      },
+      async run(commandContext) {
+        const packageName = String(commandContext.args[0] ?? "");
+        const plugins = await loadProjectPluginsModule();
+        const deactivated = await plugins.deactivateProjectPlugin(context.projectRoot, packageName);
+        const uninstalled = commandContext.flags.uninstall === true ? await removeProjectDependency(context.projectRoot, packageName) : false;
+        if (uninstalled) {
+          await runProjectDependencyInstallForProject(context, projectExecutors, context.projectRoot);
+        }
+        if (deactivated || uninstalled) {
+          const runProjectPrepare = await resolveProjectExecutor(projectExecutors, "runProjectPrepare");
+          await runProjectPrepare(context.projectRoot, context);
+        }
+        writeLine(context.stdout, deactivated ? "Removed Holo plugin activation." : "Holo plugin was not active.");
+        writeLine(context.stdout, `  - package: ${packageName}`);
+        if (commandContext.flags.uninstall === true) {
+          writeLine(context.stdout, `  - dependency: ${uninstalled ? "removed from package.json" : "not present in package.json"}`);
+        } else {
+          writeLine(context.stdout, "  - dependency: left installed");
+        }
+      }
+    },
+    {
+      name: "plugin:info",
+      aliases: ["plugins:info"],
+      description: "Show metadata for a Holo plugin package.",
+      usage: "holo plugin:info <package>",
+      source: "internal",
+      async prepare(input) {
+        const packageName = await ensureRequiredArg(context, input, 0, "Plugin package");
+        return { args: [packageName], flags: {} };
+      },
+      async run(commandContext) {
+        const packageName = String(commandContext.args[0] ?? "");
+        const plugins = await loadProjectPluginsModule();
+        const loadedPlugin = await plugins.loadHoloPluginFromPackage(context.projectRoot, packageName);
+        writePluginDetails(context, loadedPlugin);
+      }
+    },
+    {
+      name: "plugin:doctor",
+      aliases: ["plugins:doctor"],
+      description: "Validate active Holo plugin packages.",
+      usage: "holo plugin:doctor",
+      source: "internal",
+      async prepare() {
+        return { args: [], flags: {} };
+      },
+      async run() {
+        const plugins = await loadProjectPluginsModule();
+        const resolvedPlugins = await plugins.resolveProjectPlugins(context.projectRoot);
+        const failedPlugins = resolvedPlugins.filter((resolvedPlugin) => !resolvedPlugin.loaded);
+        if (resolvedPlugins.length === 0) {
+          writeLine(context.stdout, "No active Holo plugins.");
+          return;
+        }
+        for (const resolvedPlugin of resolvedPlugins) {
+          if (resolvedPlugin.loaded) {
+            writeLine(context.stdout, `Loaded ${resolvedPlugin.packageName}: ${formatPluginLabel(resolvedPlugin.loaded.definition)}`);
+            continue;
+          }
+          writeLine(context.stdout, `Failed ${resolvedPlugin.packageName}: ${resolvedPlugin.error ?? "Unknown plugin loading error."}`);
+        }
+        if (failedPlugins.length > 0) {
+          throw new Error(`${failedPlugins.length} Holo ${failedPlugins.length === 1 ? "plugin" : "plugins"} failed validation.`);
+        }
+      }
+    },
     {
       name: "auth:notifications:publish",
       description: "Publish editable auth notification definitions into the application.",
@@ -812,13 +1129,18 @@ function createInternalCommands(context, runtimeExecutor, queueExecutors = {}, p
     {
       name: "start",
       description: "Run the production framework server with Holo runtime preloads.",
-      usage: "holo start",
+      usage: "holo start [...frameworkArgs]",
       source: "internal",
-      async prepare() {
-        return { args: [], flags: {} };
+      async prepare(input) {
+        return { args: input.args, flags: input.flags };
       },
-      async run() {
+      async run(input) {
         const runProjectStartServer = await resolveProjectExecutor(projectExecutors, "runProjectStartServer");
+        const passthroughArgs = serializePassthroughInput(input);
+        if (passthroughArgs.length > 0) {
+          await runProjectStartServer(context, context.projectRoot, void 0, passthroughArgs);
+          return;
+        }
         await runProjectStartServer(context, context.projectRoot);
       }
     },
@@ -1654,10 +1976,15 @@ async function runCli(argv, io) {
     };
     const internalCommands = createInternalCommands(internalContext);
     const registry = [...internalCommands];
-    const canSkipAppDiscovery = requestedCommandName === "config:cache" || requestedCommandName === "config:clear" || requestedCommandName === "key:generate" || requestedCommandName === "new" || requestedCommandName === "install" || requestedCommandName === "agents:install" || requestedCommandName === "agent:install" || requestedCommandName === "ai:install" || requestedCommandName === "auth:notifications:publish" || requestedCommandName === "prepare" || requestedCommandName === "dev" || requestedCommandName === "build" || requestedCommandName === "cache:table" || requestedCommandName === "cache:clear" || requestedCommandName === "cache:forget" || requestedCommandName === "media:table" || requestedCommandName === "broadcast:work" || requestedCommandName === "queue:table" || requestedCommandName === "queue:failed-table" || requestedCommandName === "queue:work" || requestedCommandName === "queue:listen" || requestedCommandName === "queue:failed" || requestedCommandName === "queue:retry" || requestedCommandName === "queue:forget" || requestedCommandName === "queue:flush" || requestedCommandName === "queue:restart" || requestedCommandName === "queue:clear" || requestedCommandName === "rate-limit:clear";
+    const requestedInternalCommand = requestedCommandName ? findCommand(registry, requestedCommandName) : void 0;
+    const canSkipAppDiscovery = requestedCommandName === "config:cache" || requestedCommandName === "config:clear" || requestedCommandName === "key:generate" || requestedCommandName === "new" || requestedCommandName === "install" || requestedCommandName === "agents:install" || requestedCommandName === "agent:install" || requestedCommandName === "ai:install" || requestedCommandName === "auth:notifications:publish" || requestedCommandName === "prepare" || requestedCommandName === "dev" || requestedCommandName === "build" || requestedCommandName === "cache:table" || requestedCommandName === "cache:clear" || requestedCommandName === "cache:forget" || requestedCommandName === "media:table" || requestedCommandName === "broadcast:work" || requestedCommandName === "queue:table" || requestedCommandName === "queue:failed-table" || requestedCommandName === "queue:work" || requestedCommandName === "queue:listen" || requestedCommandName === "queue:failed" || requestedCommandName === "queue:retry" || requestedCommandName === "queue:forget" || requestedCommandName === "queue:flush" || requestedCommandName === "queue:restart" || requestedCommandName === "queue:clear" || requestedCommandName === "rate-limit:clear" || requestedCommandName === "plugin:add" || requestedCommandName === "plugins:add" || requestedCommandName === "plugin:list" || requestedCommandName === "plugins:list" || requestedCommandName === "plugin:remove" || requestedCommandName === "plugins:remove" || requestedCommandName === "plugin:info" || requestedCommandName === "plugins:info" || requestedCommandName === "plugin:doctor" || requestedCommandName === "plugins:doctor" || typeof requestedInternalCommand !== "undefined" && requestedInternalCommand.name !== "list";
     if (!canSkipAppDiscovery) {
       const initialProject = await loadProject();
-      const appCommands = (await (await loadProjectDiscoveryModule()).discoverAppCommands(projectRoot, initialProject.config)).map((entry) => createAppCommandDefinition(entry));
+      const pluginCommands = await (await loadProjectPluginsModule()).loadProjectPluginCommands(projectRoot);
+      const appCommands = [
+        ...pluginCommands,
+        ...await (await loadProjectDiscoveryModule()).discoverAppCommands(projectRoot, initialProject.config)
+      ].map((entry) => createAppCommandDefinition(entry));
       for (const appCommand of appCommands) {
         const duplicate = findCommandConflict(registry, appCommand);
         if (duplicate) {