hexbus 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -358,6 +358,14 @@ interface Telemetry {
    * Sends queued events when possible and clears the local queue.
    */
   flush(): Promise<void>;
+  /**
+   * Starts an immediate best-effort flush without requiring callers to await it.
+   *
+   * @remarks
+   * Entrypoints can call this before short-lived process exits. Implementations
+   * should not throw from this method.
+   */
+  flushBackground(): void;
   /**
    * Performs final telemetry cleanup before process exit.
    */
@@ -463,6 +471,14 @@ interface CreateContextOptions<TPackage extends string = string> {
    * Top-level commands used to identify `commandName` during argument parsing.
    */
   commands: CliCommand[];
+  /**
+   * Global flags parsed before command execution.
+   *
+   * @remarks
+   * Pass this when a product CLI needs extra global flags while keeping Hexbus'
+   * parser and context bootstrap.
+   */
+  globalFlags?: CliFlag[];
   /**
    * Application name used for config lookup, telemetry defaults, and logger
    * metadata.
@@ -1101,16 +1117,21 @@ declare function createCliLogger(level?: LogLevel): CliLogger;
 declare const globalFlags: CliFlag[];
 /**
  * Parses raw command-line arguments into command name, command args, and
- * global flags.
+ * global and caller-provided flags.
  *
  * @remarks
- * Only flags declared in `globalFlags` are parsed. Unknown flags and
- * positional arguments are preserved as command arguments unless the first
- * positional argument matches a registered top-level command.
+ * Flags declared in `globalFlags` and `flags` are parsed. Unknown flags and
+ * other positional arguments are preserved as command arguments. If the first
+ * positional argument matches a registered top-level command in `commands`, it
+ * is returned as `commandName` and removed from `commandArgs`.
  *
  * @param rawArgs - Arguments after the executable and script path.
  * @param commands - Top-level commands used to identify the command name.
- * @returns Normalized parsed arguments for context creation or custom routing.
+ * @param flags - Additional global flag definitions to parse alongside
+ * `globalFlags`. Caller-provided flags override built-in definitions that use
+ * the same primary flag name.
+ * @returns Normalized parsed output containing the matched command name,
+ * remaining command arguments, and parsed flag values keyed by primary name.
  *
  * @example
  * ```ts
@@ -1119,7 +1140,7 @@ declare const globalFlags: CliFlag[];
  * // parsed.parsedFlags.logger === 'debug'
  * ```
  */
-declare function parseCliArgs(rawArgs: string[], commands: CliCommand[]): ParsedArgs;
+declare function parseCliArgs(rawArgs: string[], commands: CliCommand[], flags?: CliFlag[]): ParsedArgs;
 /**
  * Formats a single flag for display in help output.
  *
@@ -1128,11 +1149,14 @@ declare function parseCliArgs(rawArgs: string[], commands: CliCommand[]): Parsed
  */
 declare function formatFlagHelp(flag: CliFlag): string;
 /**
- * Formats all built-in global flags for help output.
+ * Formats a provided set of flags for help output.
+ *
+ * @param flags - Flag definitions to render with `formatFlagHelp`, defaulting
+ * to `globalFlags`.
  *
- * @returns Newline-delimited help rows for `globalFlags`.
+ * @returns Newline-delimited help rows for the provided flag definitions.
  */
-declare function generateFlagsHelp(): string;
+declare function generateFlagsHelp(flags?: CliFlag[]): string;
 /**
  * Checks whether a parsed boolean flag is enabled.
  *

package/dist/index.mjs

@@ -794,18 +794,35 @@ function getPrimaryFlagName(flag) {
 	const fallback = flag.names.reduce((longest, name) => name.length > longest.length ? name : longest, "");
 	return (longName ?? fallback).replace(/^--?/, "");
 }
+function mergeFlags(flags) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const flag of globalFlags) {
+		const primaryName = getPrimaryFlagName(flag);
+		if (primaryName) merged.set(primaryName, flag);
+	}
+	for (const flag of flags) {
+		const primaryName = getPrimaryFlagName(flag);
+		if (primaryName) merged.set(primaryName, flag);
+	}
+	return [...merged.values()];
+}
 /**
 * Parses raw command-line arguments into command name, command args, and
-* global flags.
+* global and caller-provided flags.
 *
 * @remarks
-* Only flags declared in `globalFlags` are parsed. Unknown flags and
-* positional arguments are preserved as command arguments unless the first
-* positional argument matches a registered top-level command.
+* Flags declared in `globalFlags` and `flags` are parsed. Unknown flags and
+* other positional arguments are preserved as command arguments. If the first
+* positional argument matches a registered top-level command in `commands`, it
+* is returned as `commandName` and removed from `commandArgs`.
 *
 * @param rawArgs - Arguments after the executable and script path.
 * @param commands - Top-level commands used to identify the command name.
-* @returns Normalized parsed arguments for context creation or custom routing.
+* @param flags - Additional global flag definitions to parse alongside
+* `globalFlags`. Caller-provided flags override built-in definitions that use
+* the same primary flag name.
+* @returns Normalized parsed output containing the matched command name,
+* remaining command arguments, and parsed flag values keyed by primary name.
 *
 * @example
 * ```ts
@@ -814,13 +831,14 @@ function getPrimaryFlagName(flag) {
 * // parsed.parsedFlags.logger === 'debug'
 * ```
 */
-function parseCliArgs(rawArgs, commands) {
+function parseCliArgs(rawArgs, commands, flags = []) {
+	const mergedFlags = mergeFlags(flags);
 	const parsedFlags = {};
 	const potentialCommandArgs = [];
 	let commandName;
 	const commandArgs = [];
-	const knownFlagSet = new Set(globalFlags.flatMap((flag) => flag.names));
-	for (const flag of globalFlags) {
+	const knownFlagSet = new Set(mergedFlags.flatMap((flag) => flag.names));
+	for (const flag of mergedFlags) {
 		const primaryName = getPrimaryFlagName(flag);
 		if (!primaryName) continue;
 		if (flag.type === "boolean") parsedFlags[primaryName] = flag.defaultValue ?? false;
@@ -830,7 +848,7 @@ function parseCliArgs(rawArgs, commands) {
 		const arg = rawArgs[i];
 		if (typeof arg !== "string") continue;
 		let isFlag = false;
-		for (const flag of globalFlags) {
+		for (const flag of mergedFlags) {
 			if (!flag.names.includes(arg)) continue;
 			const primaryName = getPrimaryFlagName(flag);
 			if (!primaryName) continue;
@@ -868,12 +886,15 @@ function formatFlagHelp(flag) {
 	return `  ${flag.names.join(", ")}${flag.expectsValue ? " <value>" : ""}\t${flag.description}`;
 }
 /**
-* Formats all built-in global flags for help output.
+* Formats a provided set of flags for help output.
 *
-* @returns Newline-delimited help rows for `globalFlags`.
+* @param flags - Flag definitions to render with `formatFlagHelp`, defaulting
+* to `globalFlags`.
+*
+* @returns Newline-delimited help rows for the provided flag definitions.
 */
-function generateFlagsHelp() {
-	return globalFlags.map(formatFlagHelp).join("\n");
+function generateFlagsHelp(flags = globalFlags) {
+	return flags.map(formatFlagHelp).join("\n");
 }
 /**
 * Checks whether a parsed boolean flag is enabled.
@@ -964,6 +985,7 @@ function isEnvDisabled(prefix) {
 function createDisabledTelemetry() {
 	return {
 		flush: async () => {},
+		flushBackground: () => {},
 		isDisabled: () => true,
 		shutdown: async () => {},
 		trackCommand: () => {},
@@ -1020,6 +1042,9 @@ function createTelemetry(options = {}) {
 	};
 	return {
 		flush,
+		flushBackground() {
+			flush();
+		},
 		isDisabled() {
 			return false;
 		},
@@ -1139,7 +1164,7 @@ function createFileSystem(cwd) {
 async function createCliContext(options) {
 	const cwd = options.cwd ?? process.cwd();
 	const appName = options.appName ?? "cli";
-	const { commandName, commandArgs, parsedFlags } = parseCliArgs(options.rawArgs, options.commands);
+	const { commandName, commandArgs, parsedFlags } = parseCliArgs(options.rawArgs, options.commands, options.globalFlags);
 	const logger = createCliLogger(getLogLevel(parsedFlags));
 	const projectRoot = await detectProjectRoot(cwd, logger);
 	const fsUtils = createFileSystem(projectRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexbus",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Opinionated CLI framework for Inth apps.",
   "homepage": "https://github.com/inthhq/hexbus/tree/main/packages/hexbus",
   "license": "Apache-2.0",