@lenne.tech/cli 1.29.0 → 1.30.0

package/build/extensions/tools.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tools = void 0;
 const fs_1 = require("fs");
+const command_help_1 = require("../lib/command-help");
 const singleComment = Symbol('singleComment');
 const multiComment = Symbol('multiComment');
 const stripWithoutWhitespace = () => '';
@@ -27,6 +28,14 @@ class Tools {
      * Check if --help-json flag is set; if so, print the command definition as JSON and return true.
      * Commands should call this early and return immediately when it returns true.
      *
+     * In normal CLI usage the global `installHelpInterceptor` (see
+     * `src/lib/command-help.ts`) handles `--help-json` for ALL commands before
+     * their `run()` ever fires — this method is therefore mostly a no-op in
+     * production. It is still kept as a public escape hatch for tests that
+     * invoke a command's `run()` directly without the interceptor, and for
+     * legacy callers — output goes through the same `buildHelpJson` /
+     * `emitHelpJson` pair as the global path, so the schema cannot drift.
+     *
      * @param definition - The command's help definition (name, description, options, etc.)
      * @returns true if --help-json was handled (caller should return), false otherwise
      */
@@ -35,7 +44,7 @@ class Tools {
         if (!parameters.options['help-json'] && !parameters.options.helpJson) {
             return false;
         }
-        console.debug(JSON.stringify(definition, null, 2));
+        (0, command_help_1.emitHelpJson)((0, command_help_1.buildHelpJson)({ description: definition.description, name: definition.name }, definition));
         return true;
     }
     /**

package/build/lib/command-help.js

@@ -18,12 +18,16 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installHelpInterceptor = installHelpInterceptor;
+exports.isHelpJsonRequested = isHelpJsonRequested;
 exports.isHelpRequested = isHelpRequested;
 exports.loadCommandHelp = loadCommandHelp;
 exports.renderCommandHelp = renderCommandHelp;
+exports.buildHelpJson = buildHelpJson;
+exports.emitHelpJson = emitHelpJson;
 /**
- * Wrap every command's `run` so that `--help` / `-h` prints help and returns
- * without executing. Call once after `build().create()`, before `cli.run()`.
+ * Wrap every command's `run` so that `--help` / `-h` and `--help-json` print
+ * help and return without executing. Call once after `build().create()`,
+ * before `cli.run()`.
  *
  * Idempotent per command (guarded by `__helpWrapped`), so a command is never
  * double-wrapped if this runs more than once in the same process (e.g. tests).
@@ -43,6 +47,10 @@ function installHelpInterceptor(commands, defaultCommand) {
         }
         const originalRun = command.run;
         command.run = (toolbox) => {
+            if (isHelpJsonRequested(toolbox === null || toolbox === void 0 ? void 0 : toolbox.parameters)) {
+                emitHelpJson(buildHelpJson(command, loadCommandHelp(command.file)));
+                return undefined;
+            }
             if ((toolbox === null || toolbox === void 0 ? void 0 : toolbox.print) && isHelpRequested(toolbox.parameters)) {
                 renderCommandHelp(toolbox.print, command, loadCommandHelp(command.file));
                 return undefined;
@@ -52,10 +60,12 @@ function installHelpInterceptor(commands, defaultCommand) {
         command.__helpWrapped = true;
     }
 }
-/**
- * True when the invocation asks for help (`--help` or `-h`) — but NOT for
- * `--help-json` (handled separately by `tools.helpJson`).
- */
+/** True when the invocation asks for machine-readable help (`--help-json`). */
+function isHelpJsonRequested(parameters) {
+    const options = (parameters === null || parameters === void 0 ? void 0 : parameters.options) || {};
+    return options['help-json'] === true || options.helpJson === true;
+}
+/** True when the invocation asks for human-readable help (`--help` or `-h`). */
 function isHelpRequested(parameters) {
     const options = (parameters === null || parameters === void 0 ? void 0 : parameters.options) || {};
     if (options['help-json'] === true || options.helpJson === true) {
@@ -132,7 +142,7 @@ function renderCommandHelp(print, command, help) {
     }
     // Always-present global flags
     print.info(`  ${'--help, -h'.padEnd(28)} Show this help and exit (does not run the command)`);
-    print.info(`  ${'--help-json'.padEnd(28)} Machine-readable help as JSON (where provided)`);
+    print.info(`  ${'--help-json'.padEnd(28)} Machine-readable help as JSON (does not run the command)`);
     if (!options.some((o) => o.flag === '--noConfirm')) {
         print.info(`  ${'--noConfirm'.padEnd(28)} Skip confirmation prompts (where supported)`);
     }
@@ -159,3 +169,41 @@ function usagePath(command) {
     const path = command.commandPath && command.commandPath.length ? command.commandPath : [command.name || ''];
     return `lt ${path.filter(Boolean).join(' ')}`.trim();
 }
+const GLOBAL_HELP_FLAGS = [
+    { description: 'Show human-readable help; the command is NOT executed.', flag: '--help', type: 'boolean' },
+    { description: 'Alias for --help.', flag: '-h', type: 'boolean' },
+    {
+        description: 'Print this JSON description on stdout; the command is NOT executed.',
+        flag: '--help-json',
+        type: 'boolean',
+    },
+];
+/**
+ * Build the JSON shape returned by `--help-json` for a command, merging the
+ * gluegun-known metadata (name, commandPath, description, aliases) with the
+ * command's optional rich `CommandHelp` export.
+ */
+function buildHelpJson(command, help) {
+    const aliases = aliasList(command, help);
+    return {
+        aliases,
+        command: usagePath(command),
+        configuration: help === null || help === void 0 ? void 0 : help.configuration,
+        description: (help === null || help === void 0 ? void 0 : help.description) || command.description || '',
+        examples: help === null || help === void 0 ? void 0 : help.examples,
+        features: help === null || help === void 0 ? void 0 : help.features,
+        globalFlags: GLOBAL_HELP_FLAGS,
+        name: (help === null || help === void 0 ? void 0 : help.name) || command.name || '',
+        options: (help === null || help === void 0 ? void 0 : help.options) || [],
+        richHelp: Boolean(help),
+    };
+}
+/**
+ * Emit a help-json payload to stdout as a single pretty-printed JSON document.
+ * Kept tiny + side-effect-only so it can be stubbed in tests via a captured
+ * `console.log`.
+ */
+function emitHelpJson(payload) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(payload, null, 2));
+}

package/docs/commands.md

@@ -10,6 +10,7 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 ## Table of Contents
 
+- [Global Flags](#global-flags)
 - [CLI Commands](#cli-commands)
 - [Server Commands](#server-commands)
 - [Local Development Commands](#local-development-commands)
@@ -32,6 +33,44 @@ This document provides a comprehensive reference for all `lt` CLI commands. For
 
 ---
 
+## Global Flags
+
+These flags work on **every** `lt` subcommand. They are intercepted before the command's `run()` fires, so the command is never executed when one of them is set.
+
+| Flag | Description |
+|--------|-------------|
+| `--help`, `-h` | Print human-readable help (usage, aliases, options, examples). |
+| `--help-json` | Print the same help as a single JSON document on stdout. Stable contract — see shape below. Intended for AI agents and tooling that want to discover a command's surface programmatically. |
+| `--noConfirm` | Skip interactive confirmations (where supported by the command). |
+
+**`--help-json` payload shape** (`HelpJsonShape` in [src/lib/command-help.ts](../src/lib/command-help.ts)):
+
+```jsonc
+{
+  "aliases": ["c"],
+  "command": "lt server create",
+  "configuration": "commands.server.create.*",
+  "description": "Create new server",
+  "examples": ["server create --name Foo --noConfirm"],
+  "features": ["..."],
+  "globalFlags": [
+    { "flag": "--help",      "type": "boolean", "description": "..." },
+    { "flag": "-h",          "type": "boolean", "description": "..." },
+    { "flag": "--help-json", "type": "boolean", "description": "..." }
+  ],
+  "name": "create",
+  "options": [
+    { "flag": "--name", "type": "string", "required": true, "description": "Server name" }
+  ],
+  "richHelp": true
+}
+```
+
+- `richHelp: true` means the command exported a typed `CommandHelp` — `options`, `features`, `examples` and `configuration` are authoritative.
+- `richHelp: false` means only gluegun metadata was available — `options` is the empty array, but `globalFlags` is still guaranteed.
+
+---
+
 ## CLI Commands
 
 ### `lt cli create`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "lenne.Tech CLI: lt",
   "keywords": [
     "lenne.Tech",