@dereekb/dbx-cli 13.11.0 → 13.11.2

package/firebase-api-manifest/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dereekb/dbx-cli-firebase-api-manifest",
+  "version": "13.11.2",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "prettier": "3.8.3",
+    "ts-morph": "^21.0.0"
+  }
+}

package/index.cjs.js

@@ -1660,7 +1660,7 @@ function mergeOutputCommandsConfig(existing, updates) {
  * The `model.*` write scopes filtered out by {@link filterReadOnlyModelScopes}.
  *
  * Mirrors the write half of the dbx-components callModel CRUD scope set
- * (`CALL_MODEL_OIDC_SCOPES` in `@dereekb/firebase-server/oidc`) — duplicated here so the
+ * (`CALL_MODEL_OIDC_SCOPES` in `@dereekb/firebase`) — duplicated here so the
  * CLI doesn't take a server-side dependency just to know the names.
  */ var MODEL_WRITE_OIDC_SCOPES = [
     'model.create',
@@ -7093,6 +7093,15 @@ var SKIPPED_VERBS = new Set([
     'standalone'
 ]);
 var ALL_HELP_FLAG = '--all-help';
+var HELP_MODE_FLAG = '--help-mode';
+/**
+ * Default help mode when no override is supplied.
+ */ var DEFAULT_MANIFEST_HELP_MODE = 'both';
+var MANIFEST_HELP_MODES = new Set([
+    'action',
+    'params',
+    'both'
+]);
 /**
  * Default schema format when no override is supplied.
  */ var DEFAULT_MANIFEST_HELP_DATA_FORMAT = 'jsonschema';
@@ -7102,20 +7111,30 @@ var MANIFEST_HELP_DATA_FORMATS = new Set([
     'both'
 ]);
 var DATA_HELP_FLAG = '--data-help';
+/**
+ * Default name of the parent command that groups all per-model manifest commands.
+ * Surfaces as `<cli> model <model> <action>` so the top-level `--help` stays focused
+ * on first-class commands instead of dumping every model.
+ */ var DEFAULT_MANIFEST_MODEL_COMMAND_NAME = 'model';
 /**
  * Builds yargs `CommandModule[]` from a generated {@link CliApiManifest}.
  *
- * Groups entries by `model`, emitting one parent command per model and one child action per entry
- * (named `<verb>` or `<verb>-<specifier>`). Each child accepts `--data <json>`, validates the
+ * Returns a single parent command (default name `model`) whose subcommands are the per-model
+ * dispatch commands. Each per-model subcommand has one child action per entry
+ * (named `<verb>` or `<verb>-<specifier>`). Each leaf accepts `--data <json>`, validates the
  * payload against the entry's bound arktype validator (when present), and dispatches via the
  * authenticated CLI context's `callModel` helper. Standalone entries are skipped because they
  * are not dispatched through the `/model/call` endpoint.
  *
+ * Wrapping under `model` keeps the top-level `--help` short — users invoke
+ * `<cli> model --help` to see the full list of available models.
+ *
  * @param manifest - The generated manifest array.
  * @param options - Optional overrides; see {@link BuildManifestCommandsOptions}.
- * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`.
+ * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`. Empty
+ *   when the manifest has no callable entries.
  */ function buildManifestCommands(manifest, options) {
-    var _ref, _ref1, _ref2, _ref3;
+    var _ref, _ref1, _ref2, _ref3, _ref4, _ref5;
     var callable = manifest.filter(function(e) {
         return !SKIPPED_VERBS.has(e.verb);
     });
@@ -7147,38 +7166,57 @@ var DATA_HELP_FLAG = '--data-help';
             }
         }
     }
+    if (byModel.size === 0) {
+        return [];
+    }
     var argv = (_ref = options === null || options === void 0 ? void 0 : options.argv) !== null && _ref !== void 0 ? _ref : process.argv;
     var dataHelpFormat = (_ref1 = options === null || options === void 0 ? void 0 : options.dataHelpFormat) !== null && _ref1 !== void 0 ? _ref1 : detectDataHelpFormat(argv);
-    var focusHelp = ((_ref2 = options === null || options === void 0 ? void 0 : options.focusHelpOnDataHelp) !== null && _ref2 !== void 0 ? _ref2 : true) && hasDataHelpFlag(argv) && !hasAllHelpFlag(argv);
-    var hideOnFocus = focusHelp ? (_ref3 = options === null || options === void 0 ? void 0 : options.hiddenWhenFocused) !== null && _ref3 !== void 0 ? _ref3 : STANDARD_GLOBAL_OPTION_NAMES : [];
-    var commands = [];
-    var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
-    try {
-        for(var _iterator1 = _to_consumable_array(byModel.entries()).sort(function(param, param1) {
-            var _param = _sliced_to_array(param, 1), a = _param[0], _param1 = _sliced_to_array(param1, 1), b = _param1[0];
-            return a.localeCompare(b);
-        })[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
-            var _step_value = _sliced_to_array(_step1.value, 2), model = _step_value[0], entries = _step_value[1];
-            commands.push(buildModelCommand(model, entries, {
-                dataHelpFormat: dataHelpFormat,
-                hideOnFocus: hideOnFocus
-            }));
-        }
-    } catch (err) {
-        _didIteratorError1 = true;
-        _iteratorError1 = err;
-    } finally{
-        try {
-            if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
-                _iterator1.return();
-            }
-        } finally{
-            if (_didIteratorError1) {
-                throw _iteratorError1;
+    var helpMode = (_ref2 = options === null || options === void 0 ? void 0 : options.helpMode) !== null && _ref2 !== void 0 ? _ref2 : detectHelpMode(argv);
+    var focusHelp = ((_ref3 = options === null || options === void 0 ? void 0 : options.focusHelpOnDataHelp) !== null && _ref3 !== void 0 ? _ref3 : true) && hasDataHelpFlag(argv) && !hasAllHelpFlag(argv);
+    var hideOnFocus = focusHelp ? (_ref4 = options === null || options === void 0 ? void 0 : options.hiddenWhenFocused) !== null && _ref4 !== void 0 ? _ref4 : STANDARD_GLOBAL_OPTION_NAMES : [];
+    var modelCommandName = (_ref5 = options === null || options === void 0 ? void 0 : options.modelCommandName) !== null && _ref5 !== void 0 ? _ref5 : DEFAULT_MANIFEST_MODEL_COMMAND_NAME;
+    var sortedModels = _to_consumable_array(byModel.entries()).sort(function(param, param1) {
+        var _param = _sliced_to_array(param, 1), a = _param[0], _param1 = _sliced_to_array(param1, 1), b = _param1[0];
+        return a.localeCompare(b);
+    });
+    var context = {
+        dataHelpFormat: dataHelpFormat,
+        helpMode: helpMode,
+        hideOnFocus: hideOnFocus
+    };
+    return [
+        {
+            command: "".concat(modelCommandName, " <model>"),
+            describe: "Call typed model APIs (".concat(byModel.size, " model").concat(byModel.size === 1 ? '' : 's', "). Use `").concat(modelCommandName, " --help` to list them."),
+            builder: function builder(yargs) {
+                var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                try {
+                    for(var _iterator = sortedModels[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                        var _step_value = _sliced_to_array(_step.value, 2), model = _step_value[0], entries = _step_value[1];
+                        yargs.command(buildModelCommand(model, entries, context));
+                    }
+                } catch (err) {
+                    _didIteratorError = true;
+                    _iteratorError = err;
+                } finally{
+                    try {
+                        if (!_iteratorNormalCompletion && _iterator.return != null) {
+                            _iterator.return();
+                        }
+                    } finally{
+                        if (_didIteratorError) {
+                            throw _iteratorError;
+                        }
+                    }
+                }
+                hideGlobalOptions(yargs, hideOnFocus);
+                return yargs.demandCommand(1, 'Please specify a model.');
+            },
+            handler: function handler() {
+                return undefined;
             }
         }
-    }
-    return commands;
+    ];
 }
 /**
  * Returns true if `--data-help` (with or without a value) appears anywhere in
@@ -7236,6 +7274,38 @@ var DATA_HELP_FLAG = '--data-help';
 function parseDataHelpFormat(value) {
     return MANIFEST_HELP_DATA_FORMATS.has(value) ? value : undefined;
 }
+/**
+ * Inspects an argv array for `--help-mode=<mode>` or `--help-mode <mode>` and
+ * returns the requested {@link ManifestHelpMode}. Unrecognized values fall
+ * back to {@link DEFAULT_MANIFEST_HELP_MODE}.
+ *
+ * Implemented as a raw argv scan (rather than going through yargs) because the
+ * value is needed when each command's builder runs — which is before yargs
+ * parses argv.
+ *
+ * @param argv - argv to inspect (defaults to `process.argv`).
+ * @returns The detected mode, or {@link DEFAULT_MANIFEST_HELP_MODE}.
+ */ function detectHelpMode() {
+    var argv = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : process.argv;
+    var result = DEFAULT_MANIFEST_HELP_MODE;
+    for(var i = 0; i < argv.length; i++){
+        var arg = argv[i];
+        if (arg.startsWith("".concat(HELP_MODE_FLAG, "="))) {
+            var _parseHelpMode;
+            result = (_parseHelpMode = parseHelpMode(arg.slice(HELP_MODE_FLAG.length + 1))) !== null && _parseHelpMode !== void 0 ? _parseHelpMode : result;
+            break;
+        }
+        if (arg === HELP_MODE_FLAG && i + 1 < argv.length) {
+            var _parseHelpMode1;
+            result = (_parseHelpMode1 = parseHelpMode(argv[i + 1])) !== null && _parseHelpMode1 !== void 0 ? _parseHelpMode1 : result;
+            break;
+        }
+    }
+    return result;
+}
+function parseHelpMode(value) {
+    return MANIFEST_HELP_MODES.has(value) ? value : undefined;
+}
 function buildModelCommand(model, entries, context) {
     return {
         command: "".concat(model, " <action>"),
@@ -7270,14 +7340,15 @@ function buildModelCommand(model, entries, context) {
     };
 }
 function buildEntryCommand(entry, context) {
-    var _entry_description;
+    var _oneLineDescription;
     var action = entry.specifier && entry.specifier !== '_' ? "".concat(entry.verb, "-").concat(entry.specifier) : entry.verb;
     var specPart = entry.specifier && entry.specifier !== '_' ? ' ' + entry.specifier : '';
-    var describe = (_entry_description = entry.description) !== null && _entry_description !== void 0 ? _entry_description : "".concat(entry.verb).concat(specPart, " on ").concat(entry.model);
-    var epilogue = buildEntryEpilogue(entry, context.dataHelpFormat);
+    var fallbackDescribe = "".concat(entry.verb).concat(specPart, " on ").concat(entry.model);
+    var describeOneLine = (_oneLineDescription = oneLineDescription(entry.description)) !== null && _oneLineDescription !== void 0 ? _oneLineDescription : fallbackDescribe;
+    var epilogue = buildEntryEpilogue(entry, context);
     return {
         command: action,
-        describe: describe,
+        describe: describeOneLine,
         builder: function builder(yargs) {
             var y = yargs.option('data', {
                 type: 'string',
@@ -7326,6 +7397,12 @@ function buildEntryCommand(entry, context) {
         }
     };
 }
+function oneLineDescription(description) {
+    var _description_split_;
+    if (!description) return undefined;
+    var firstLine = (_description_split_ = description.split('\n', 1)[0]) === null || _description_split_ === void 0 ? void 0 : _description_split_.trim();
+    return firstLine && firstLine.length > 0 ? firstLine : undefined;
+}
 function hideGlobalOptions(yargs, names) {
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
@@ -7349,37 +7426,145 @@ function hideGlobalOptions(yargs, names) {
     }
 }
 /**
- * Builds the help epilogue for a manifest-driven command. Surfaces the params
- * arktype validator (as JSON Schema and/or the arktype expression — see
- * {@link ManifestHelpDataFormat}) along with the params/result type names and
- * the source `.api.ts` path for traceability. Designed to give both humans
- * and LLM agents enough information from `--help` alone to construct a valid
- * `--data` payload.
+ * Builds the help epilogue for a manifest-driven command. Surfaces the action
+ * description JSDoc, the params interface description and per-field
+ * descriptions, the params arktype validator (as JSON Schema and/or arktype
+ * expression — see {@link ManifestHelpDataFormat}), and the source `.api.ts`
+ * path for traceability. Designed to give both humans and LLM agents enough
+ * information from `--help` alone to understand a command and construct a
+ * valid `--data` payload.
  *
  * @param entry - Manifest entry whose metadata becomes the help epilogue.
- * @param dataHelpFormat - Format used for the `Params Schema` section.
+ * @param context - Builder context controlling schema format and which sections
+ *   to render (see {@link ManifestHelpMode}).
  * @returns Multi-section epilogue string, or `undefined` when the entry has no
  *   metadata worth surfacing.
- */ function buildEntryEpilogue(entry, dataHelpFormat) {
-    var _sections;
+ */ function buildEntryEpilogue(entry, context) {
+    var dataHelpFormat = context.dataHelpFormat, helpMode = context.helpMode;
+    var showAction = helpMode === 'action' || helpMode === 'both';
+    var showParams = helpMode === 'params' || helpMode === 'both';
     var sections = [];
-    if (entry.paramsTypeName) {
-        sections.push("Params: ".concat(entry.paramsTypeName));
-    }
-    var schemaSections = renderParamsSchemaSections(entry, dataHelpFormat);
-    (_sections = sections).push.apply(_sections, _to_consumable_array(schemaSections));
-    if (entry.resultTypeName) {
-        sections.push("Result: ".concat(entry.resultTypeName));
+    if (showAction) {
+        var actionSection = buildActionSection(entry);
+        if (actionSection) sections.push(actionSection);
+    }
+    var schemaSections = [];
+    if (showParams) {
+        var _sections;
+        var paramsSection = buildParamsSection(entry);
+        if (paramsSection) sections.push(paramsSection);
+        schemaSections = renderParamsSchemaSections(entry, dataHelpFormat);
+        (_sections = sections).push.apply(_sections, _to_consumable_array(schemaSections));
+        var resultSection = buildResultSection(entry);
+        if (resultSection) {
+            sections.push(resultSection);
+        } else if (entry.resultTypeName) {
+            sections.push("Result: ".concat(entry.resultTypeName));
+        }
     }
     if (entry.sourceFile) {
         sections.push("Source: ".concat(entry.sourceFile));
     }
-    if (schemaSections.length > 0 && dataHelpFormat !== 'both') {
+    if (showParams && schemaSections.length > 0 && dataHelpFormat !== 'both') {
         var other = dataHelpFormat === 'jsonschema' ? 'arktype' : 'jsonschema';
         sections.push("(Pass --data-help=".concat(other, " or --data-help=both to switch the schema format above.)"));
     }
+    if (helpMode === 'both' && (entry.description || entry.paramsTypeDescription || entry.paramsFields && entry.paramsFields.length > 0)) {
+        sections.push("(Pass --help-mode=action or --help-mode=params to focus this help on a single section.)");
+    }
     return sections.length > 0 ? sections.join('\n\n') : undefined;
 }
+function buildActionSection(entry) {
+    if (!entry.description) return undefined;
+    return "About:\n".concat(indentLines(entry.description, '  '));
+}
+function buildParamsSection(entry) {
+    if (!entry.paramsTypeName && !entry.paramsTypeDescription && !(entry.paramsFields && entry.paramsFields.length > 0)) {
+        return undefined;
+    }
+    var lines = [];
+    if (entry.paramsTypeName) {
+        lines.push("Params: ".concat(entry.paramsTypeName));
+    }
+    if (entry.paramsTypeDescription) {
+        lines.push(indentLines(entry.paramsTypeDescription, '  '));
+    }
+    if (entry.paramsFields && entry.paramsFields.length > 0) {
+        lines.push('');
+        lines.push('Fields:');
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = entry.paramsFields[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var field = _step.value;
+                var header = "  - ".concat(field.name, ": ").concat(field.typeText);
+                lines.push(header);
+                if (field.description) {
+                    lines.push(indentLines(field.description, '      '));
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function buildResultSection(entry) {
+    if (!entry.resultTypeDescription && !(entry.resultFields && entry.resultFields.length > 0)) {
+        return undefined;
+    }
+    var lines = [];
+    if (entry.resultTypeName) {
+        lines.push("Result: ".concat(entry.resultTypeName));
+    }
+    if (entry.resultTypeDescription) {
+        lines.push(indentLines(entry.resultTypeDescription, '  '));
+    }
+    if (entry.resultFields && entry.resultFields.length > 0) {
+        lines.push('');
+        lines.push('Fields:');
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = entry.resultFields[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var field = _step.value;
+                var header = "  - ".concat(field.name, ": ").concat(field.typeText);
+                lines.push(header);
+                if (field.description) {
+                    lines.push(indentLines(field.description, '      '));
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function indentLines(text, indent) {
+    return text.split('\n').map(function(line) {
+        return "".concat(indent).concat(line);
+    }).join('\n');
+}
 function renderParamsSchemaSections(entry, dataHelpFormat) {
     var sections = [];
     if (!entry.paramsValidator) {
@@ -8092,6 +8277,8 @@ exports.CliError = CliError;
 exports.DEFAULT_CLI_OIDC_SCOPES = DEFAULT_CLI_OIDC_SCOPES;
 exports.DEFAULT_CLI_SECRET_PATTERNS = DEFAULT_CLI_SECRET_PATTERNS;
 exports.DEFAULT_MANIFEST_HELP_DATA_FORMAT = DEFAULT_MANIFEST_HELP_DATA_FORMAT;
+exports.DEFAULT_MANIFEST_HELP_MODE = DEFAULT_MANIFEST_HELP_MODE;
+exports.DEFAULT_MANIFEST_MODEL_COMMAND_NAME = DEFAULT_MANIFEST_MODEL_COMMAND_NAME;
 exports.DUMP_MERGE_MODES = DUMP_MERGE_MODES;
 exports.DUMP_OUTPUT_MODES = DUMP_OUTPUT_MODES;
 exports.MODEL_WRITE_OIDC_SCOPES = MODEL_WRITE_OIDC_SCOPES;
@@ -8122,6 +8309,7 @@ exports.createOutputCommand = createOutputCommand;
 exports.createOutputMiddleware = createOutputMiddleware;
 exports.defaultDoctorChecks = defaultDoctorChecks;
 exports.detectDataHelpFormat = detectDataHelpFormat;
+exports.detectHelpMode = detectHelpMode;
 exports.discoverOidcMetadata = discoverOidcMetadata;
 exports.dumpTimestamp = dumpTimestamp;
 exports.exchangeAuthorizationCode = exchangeAuthorizationCode;