@optique/discover 1.2.0-dev.2298 → 1.2.0-dev.2302

package/README.md

@@ -69,6 +69,7 @@ await runProgram({
     version: "1.0.0",
     brief: message`Administrative command-line tools.`,
   },
+  commandList: "top-level",
 });
 ~~~~
 
@@ -156,6 +157,9 @@ Entry files named `index` map to their containing command path, so
 defines `user`.  Use `entryFileName` to choose another entry name or disable
 this rule.  `commandsFromModules()` applies the same path rules to module map
 keys after stripping its `base` option.
+For large command trees, pass `commandList: "top-level"` to keep root help
+focused on first-level command groups while subcommand help remains available
+through `<command> --help`.
 
 For more resources, see the [docs] and the [*examples/*](/examples/)
 directory.

package/dist/cli.cjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 const require_chunk = require('./chunk-CUT6urMc.cjs');
 require('./command-C-NgG0KJ.cjs');
-require('./src-B4qtzrut.cjs');
-const require_generator = require('./generator-DNRlBDyF.cjs');
+require('./src-CPtrcNkd.cjs');
+const require_generator = require('./generator-Dc9I4tTs.cjs');
 const require_main_check = require('./main-check-CwunSNpK.cjs');
 const __optique_core_constructs = require_chunk.__toESM(require("@optique/core/constructs"));
 const __optique_core_message = require_chunk.__toESM(require("@optique/core/message"));
@@ -15,7 +15,7 @@ const node_process = require_chunk.__toESM(require("node:process"));
 
 //#region deno.json
 var name = "@optique/discover";
-var version = "1.2.0-dev.2298+a0394b06";
+var version = "1.2.0-dev.2302+77665cb5";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import "./command-9sgrJtwh.js";
-import "./src-CKPihqEZ.js";
-import { watchCommandsModule, writeCommandsModule } from "./generator-B-dPfnHz.js";
+import "./src-CCeOMJRj.js";
+import { watchCommandsModule, writeCommandsModule } from "./generator-wZHULCZH.js";
 import { isMainModuleUrl } from "./main-check-mMnKfUZs.js";
 import { object } from "@optique/core/constructs";
 import { message } from "@optique/core/message";
@@ -14,7 +14,7 @@ import process from "node:process";
 
 //#region deno.json
 var name = "@optique/discover";
-var version = "1.2.0-dev.2298+a0394b06";
+var version = "1.2.0-dev.2302+77665cb5";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{generator-DNRlBDyF.cjs → generator-Dc9I4tTs.cjs}

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_src = require('./src-B4qtzrut.cjs');
+const require_src = require('./src-CPtrcNkd.cjs');
 const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
 const node_path = require_chunk.__toESM(require("node:path"));
 const node_url = require_chunk.__toESM(require("node:url"));

package/dist/{generator-B-dPfnHz.js → generator-wZHULCZH.js}

@@ -1,4 +1,4 @@
-import { getDefaultExtensions } from "./src-CKPihqEZ.js";
+import { getDefaultExtensions } from "./src-CCeOMJRj.js";
 import { mkdir, readdir, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, posix, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/generator.cjs

@@ -1,6 +1,6 @@
 require('./command-C-NgG0KJ.cjs');
-require('./src-B4qtzrut.cjs');
-const require_generator = require('./generator-DNRlBDyF.cjs');
+require('./src-CPtrcNkd.cjs');
+const require_generator = require('./generator-Dc9I4tTs.cjs');
 
 exports.generateCommandsModule = require_generator.generateCommandsModule;
 exports.watchCommandsModule = require_generator.watchCommandsModule;

package/dist/generator.js

@@ -1,5 +1,5 @@
 import "./command-9sgrJtwh.js";
-import "./src-CKPihqEZ.js";
-import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-B-dPfnHz.js";
+import "./src-CCeOMJRj.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-wZHULCZH.js";
 
 export { generateCommandsModule, watchCommandsModule, writeCommandsModule };

package/dist/index.cjs

@@ -1,5 +1,5 @@
 const require_command = require('./command-C-NgG0KJ.cjs');
-const require_src = require('./src-B4qtzrut.cjs');
+const require_src = require('./src-CPtrcNkd.cjs');
 
 exports.commandsFromModules = require_src.commandsFromModules;
 exports.createProgramParser = require_src.createProgramParser;

package/dist/index.d.cts

@@ -294,7 +294,7 @@ declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromM
  *         duplicated.
  * @since 1.1.0
  */
-declare function createProgramParser(commands: readonly CommandEntry[], metadata?: ProgramHelpMetadata): FluentParser<Mode, ProgramInvocation, unknown>;
+declare function createProgramParser(commands: readonly CommandEntry[], options?: CreateProgramParserOptions): FluentParser<Mode, ProgramInvocation, unknown>;
 /**
  * Discovers and runs a command program.
  *
@@ -325,5 +325,18 @@ interface ProgramHelpMetadata {
    */
   readonly footer?: Message;
 }
+/**
+ * Options for {@link createProgramParser}.
+ *
+ * @since 1.2.0
+ */
+interface CreateProgramParserOptions extends ProgramHelpMetadata {
+  /**
+   * How to render command lists in top-level help pages.
+   *
+   * @default `"recursive"`
+   */
+  readonly commandList?: RunOptions["commandList"];
+}
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, CreateProgramParserOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.d.ts

@@ -294,7 +294,7 @@ declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromM
  *         duplicated.
  * @since 1.1.0
  */
-declare function createProgramParser(commands: readonly CommandEntry[], metadata?: ProgramHelpMetadata): FluentParser<Mode, ProgramInvocation, unknown>;
+declare function createProgramParser(commands: readonly CommandEntry[], options?: CreateProgramParserOptions): FluentParser<Mode, ProgramInvocation, unknown>;
 /**
  * Discovers and runs a command program.
  *
@@ -325,5 +325,18 @@ interface ProgramHelpMetadata {
    */
   readonly footer?: Message;
 }
+/**
+ * Options for {@link createProgramParser}.
+ *
+ * @since 1.2.0
+ */
+interface CreateProgramParserOptions extends ProgramHelpMetadata {
+  /**
+   * How to render command lists in top-level help pages.
+   *
+   * @default `"recursive"`
+   */
+  readonly commandList?: RunOptions["commandList"];
+}
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, CreateProgramParserOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.js

@@ -1,4 +1,4 @@
 import { defineCommand, isCommand } from "./command-9sgrJtwh.js";
-import { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram } from "./src-CKPihqEZ.js";
+import { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram } from "./src-CCeOMJRj.js";
 
 export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/{src-CKPihqEZ.js → src-CCeOMJRj.js}

@@ -9,7 +9,7 @@ import { posix, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dispatchByMode, inheritAnnotations, mapModeValue, wrapForMode } from "@optique/core/extension";
 import { fluent } from "@optique/core/fluent";
-import { mergeHidden } from "@optique/core/usage";
+import { isDocHidden, mergeHidden } from "@optique/core/usage";
 
 //#region src/index.ts
 /**
@@ -129,7 +129,7 @@ function commandsFromModules(modules, options = {}) {
 *         duplicated.
 * @since 1.1.0
 */
-function createProgramParser(commands, metadata = {}) {
+function createProgramParser(commands, options = {}) {
 	if (commands.length < 1) throw new TypeError("createProgramParser() requires at least one command.");
 	const sortedCommands = sortCommands(commands);
 	rejectDuplicatePaths(sortedCommands.map((entry) => ({
@@ -138,7 +138,7 @@ function createProgramParser(commands, metadata = {}) {
 	})));
 	const rootNode = buildCommandTree(sortedCommands);
 	const parser = buildNodeParser(rootNode);
-	return fluent(withRootDocs(parser, sortedCommands, metadata));
+	return fluent(withRootDocs(parser, sortedCommands, options));
 }
 /**
 * Discovers and runs a command program.
@@ -159,7 +159,10 @@ async function runProgram(options) {
 		extensions: options.extensions,
 		entryFileName: options.entryFileName
 	});
-	const parser = createProgramParser(commands, options.metadata);
+	const parser = createProgramParser(commands, {
+		...options.metadata,
+		commandList: options.commandList
+	});
 	const invocation = await runAsync(parser, buildRunOptions(options));
 	await dispatchInvocation(invocation, options.hooks);
 }
@@ -724,8 +727,8 @@ function createLeafParser(commandDefinition, path, includeMetadata = false) {
 function withRootDocs(parser, commands, metadata) {
 	const rootState = parser.initialState;
 	const rootCommand = commands.find((entry) => entry.path.length < 1);
-	const listedCommands = commands.filter((entry) => entry.path.length > 0);
 	const commandsByPath = new Map(commands.map((entry) => [commandPathKey(entry.path), entry.command]));
+	const listedCommands = rootListedCommands(commands, commandsByPath, metadata.commandList ?? "recursive");
 	const rootDocs = () => {
 		const fragments = [...rootCommand?.command.parser.getDocFragments({ kind: "unavailable" }).fragments ?? []];
 		if (listedCommands.length > 0) fragments.push({
@@ -754,6 +757,36 @@ function withRootDocs(parser, commands, metadata) {
 		}
 	};
 }
+function rootListedCommands(commands, commandsByPath, commandList) {
+	const listedCommands = commands.filter((entry) => entry.path.length > 0);
+	if (commandList !== "top-level" || listedCommands.length < 1) return listedCommands;
+	const topLevelEntries = /* @__PURE__ */ new Map();
+	for (const entry of listedCommands) {
+		const segment = entry.path[0];
+		if (segment == null) continue;
+		const path = [segment];
+		const key = commandPathKey(path);
+		if (topLevelEntries.has(key)) continue;
+		const command$1 = commandsByPath.get(key);
+		if (command$1 != null) topLevelEntries.set(key, {
+			path,
+			command: command$1
+		});
+		else if (!isDocHidden(commandPathHidden(entry.path, commandsByPath))) topLevelEntries.set(key, {
+			path,
+			command: withoutCommandDocs(entry.command)
+		});
+	}
+	return [...topLevelEntries.values()];
+}
+function withoutCommandDocs(commandDefinition) {
+	if (commandDefinition.metadata == null) return commandDefinition;
+	const { brief: _brief, description: _description,...metadata } = commandDefinition.metadata;
+	return {
+		...commandDefinition,
+		metadata
+	};
+}
 function commandPathHidden(path, commandsByPath) {
 	let hidden;
 	for (let length = 1; length <= path.length; length++) hidden = mergeHidden(hidden, commandsByPath.get(commandPathKey(path.slice(0, length)))?.metadata?.hidden);

package/dist/{src-B4qtzrut.cjs → src-CPtrcNkd.cjs}

@@ -130,7 +130,7 @@ function commandsFromModules(modules, options = {}) {
 *         duplicated.
 * @since 1.1.0
 */
-function createProgramParser(commands, metadata = {}) {
+function createProgramParser(commands, options = {}) {
 	if (commands.length < 1) throw new TypeError("createProgramParser() requires at least one command.");
 	const sortedCommands = sortCommands(commands);
 	rejectDuplicatePaths(sortedCommands.map((entry) => ({
@@ -139,7 +139,7 @@ function createProgramParser(commands, metadata = {}) {
 	})));
 	const rootNode = buildCommandTree(sortedCommands);
 	const parser = buildNodeParser(rootNode);
-	return (0, __optique_core_fluent.fluent)(withRootDocs(parser, sortedCommands, metadata));
+	return (0, __optique_core_fluent.fluent)(withRootDocs(parser, sortedCommands, options));
 }
 /**
 * Discovers and runs a command program.
@@ -160,7 +160,10 @@ async function runProgram(options) {
 		extensions: options.extensions,
 		entryFileName: options.entryFileName
 	});
-	const parser = createProgramParser(commands, options.metadata);
+	const parser = createProgramParser(commands, {
+		...options.metadata,
+		commandList: options.commandList
+	});
 	const invocation = await (0, __optique_run.runAsync)(parser, buildRunOptions(options));
 	await dispatchInvocation(invocation, options.hooks);
 }
@@ -725,8 +728,8 @@ function createLeafParser(commandDefinition, path, includeMetadata = false) {
 function withRootDocs(parser, commands, metadata) {
 	const rootState = parser.initialState;
 	const rootCommand = commands.find((entry) => entry.path.length < 1);
-	const listedCommands = commands.filter((entry) => entry.path.length > 0);
 	const commandsByPath = new Map(commands.map((entry) => [commandPathKey(entry.path), entry.command]));
+	const listedCommands = rootListedCommands(commands, commandsByPath, metadata.commandList ?? "recursive");
 	const rootDocs = () => {
 		const fragments = [...rootCommand?.command.parser.getDocFragments({ kind: "unavailable" }).fragments ?? []];
 		if (listedCommands.length > 0) fragments.push({
@@ -755,6 +758,36 @@ function withRootDocs(parser, commands, metadata) {
 		}
 	};
 }
+function rootListedCommands(commands, commandsByPath, commandList) {
+	const listedCommands = commands.filter((entry) => entry.path.length > 0);
+	if (commandList !== "top-level" || listedCommands.length < 1) return listedCommands;
+	const topLevelEntries = /* @__PURE__ */ new Map();
+	for (const entry of listedCommands) {
+		const segment = entry.path[0];
+		if (segment == null) continue;
+		const path = [segment];
+		const key = commandPathKey(path);
+		if (topLevelEntries.has(key)) continue;
+		const command$1 = commandsByPath.get(key);
+		if (command$1 != null) topLevelEntries.set(key, {
+			path,
+			command: command$1
+		});
+		else if (!(0, __optique_core_usage.isDocHidden)(commandPathHidden(entry.path, commandsByPath))) topLevelEntries.set(key, {
+			path,
+			command: withoutCommandDocs(entry.command)
+		});
+	}
+	return [...topLevelEntries.values()];
+}
+function withoutCommandDocs(commandDefinition) {
+	if (commandDefinition.metadata == null) return commandDefinition;
+	const { brief: _brief, description: _description,...metadata } = commandDefinition.metadata;
+	return {
+		...commandDefinition,
+		metadata
+	};
+}
 function commandPathHidden(path, commandsByPath) {
 	let hidden;
 	for (let length = 1; length <= path.length; length++) hidden = (0, __optique_core_usage.mergeHidden)(hidden, commandsByPath.get(commandPathKey(path.slice(0, length)))?.metadata?.hidden);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/discover",
-  "version": "1.2.0-dev.2298",
+  "version": "1.2.0-dev.2302",
   "description": "Runtime-aware command discovery for Optique CLI programs",
   "keywords": [
     "CLI",
@@ -83,8 +83,8 @@
     "optique-discover": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "1.2.0-dev.2298+a0394b06",
-    "@optique/run": "1.2.0-dev.2298+a0394b06"
+    "@optique/core": "1.2.0-dev.2302+77665cb5",
+    "@optique/run": "1.2.0-dev.2302+77665cb5"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",