@dereekb/dbx-cli 13.11.1 → 13.11.3

package/index.cjs.js

@@ -274,6 +274,7 @@ var _errorMapper;
  * @param extension - File extension to append (`json` for full responses, `ndjson` for streaming dumps).
  * @param suffix - Optional suffix appended to the filename before the extension.
  * @returns The absolute file path, or `undefined` when `dumpDir` is not configured.
+ * @__NO_SIDE_EFFECTS__
  */ function buildDumpFilePath(extension, suffix) {
     var dumpDir = _outputOptions.dumpDir, commandPath = _outputOptions.commandPath;
     if (!dumpDir) {
@@ -410,6 +411,7 @@ function pickFromObject(obj, fields) {
  *
  * @param error - The thrown value to convert.
  * @returns The structured {@link CliErrorOutput}.
+ * @__NO_SIDE_EFFECTS__
  */ function buildErrorOutput(error) {
     if (_errorMapper) {
         var mapped = _errorMapper(error);
@@ -671,6 +673,7 @@ function trimSlash$1(url) {
  * @param input - Optional slot configuration.
  * @param input.notInitializedMessage - Custom error message thrown by `require()` when the slot is unset.
  * @returns A new {@link ContextSlot} for type `T`.
+ * @__NO_SIDE_EFFECTS__
  */ function createContextSlot(input) {
     var _ref;
     var _value;
@@ -715,6 +718,7 @@ var getCliContext = _cliContextSlot.get;
  * @param input.env - The resolved {@link CliEnvConfig} for the active env.
  * @param input.accessToken - The Bearer access token to include on outgoing API calls.
  * @returns The constructed {@link CliContext}.
+ * @__NO_SIDE_EFFECTS__
  */ function createCliContext(input) {
     return {
         cliName: input.cliName,
@@ -914,6 +918,7 @@ function _ts_generator$e(thisArg, body) {
  *
  * @param spec - The command spec describing the yargs command surface plus how to map argv into the typed call params and the result.
  * @returns A yargs `CommandModule` whose handler runs the spec against the active CLI context.
+ * @__NO_SIDE_EFFECTS__
  */ function createCallModelCommand(spec) {
     return {
         command: spec.command,
@@ -1660,7 +1665,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',
@@ -1788,6 +1793,7 @@ function nonEmpty(value) {
  * @param config.cliName - The CLI's binary name; the default config dir is `~/.<cliName>`.
  * @param config.configDirOverride - Optional override that replaces the default config directory verbatim (used by tests).
  * @returns The {@link CliPaths} pointing at `configDir`, the config file, and the token cache file.
+ * @__NO_SIDE_EFFECTS__
  */ function buildCliPaths(config) {
     var _config_configDirOverride;
     var configDir = (_config_configDirOverride = config.configDirOverride) !== null && _config_configDirOverride !== void 0 ? _config_configDirOverride : node_path.join(node_os.homedir(), ".".concat(config.cliName));
@@ -1807,6 +1813,7 @@ function nonEmpty(value) {
  * @param input - The cache store inputs.
  * @param input.tokenCachePath - Absolute path to the JSON file backing the cache.
  * @returns A {@link CliTokenCacheStore} keyed by env name.
+ * @__NO_SIDE_EFFECTS__
  */ function createCliTokenCacheStore(input) {
     return nestjs.createMemoizedJsonFileAsyncKeyedValueCache({
         filePath: input.tokenCachePath
@@ -2534,6 +2541,7 @@ function _ts_generator$a(thisArg, body) {
  * @param input.state - The opaque OAuth state token used for CSRF protection.
  * @param input.codeChallenge - The PKCE code challenge derived from the verifier.
  * @returns The full authorization URL with all OAuth params merged in.
+ * @__NO_SIDE_EFFECTS__
  */ function buildAuthorizationUrl(input) {
     var _input_scopes;
     var authParams = {
@@ -3066,6 +3074,7 @@ function maskEnv$1(env) {
  * @param input.envVarName - Override for the env-name env var. Defaults to `<CLINAME>_ENV` (e.g. `DEMO_CLI_ENV`).
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs `CommandModule` exposing the full `auth` subcommand surface.
+ * @__NO_SIDE_EFFECTS__
  */ function createAuthCommand(input) {
     var _input_envVarName;
     var cliName = input.cliName;
@@ -4413,6 +4422,7 @@ function _ts_generator$8(thisArg, body) {
  * @param input.checks - Additional checks to append after the default check list.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs `CommandModule` exposing the `doctor` command.
+ * @__NO_SIDE_EFFECTS__
  */ function createDoctorCommand(input) {
     var _input_checks;
     var cliName = input.cliName;
@@ -4851,6 +4861,7 @@ function resolveEnvWithDefault(input) {
  * @param input.cliName - The CLI's binary name.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs `CommandModule` exposing the full `env` subcommand surface.
+ * @__NO_SIDE_EFFECTS__
  */ function createEnvCommand(input) {
     var paths = buildCliPaths({
         cliName: input.cliName
@@ -5466,6 +5477,7 @@ function _ts_generator$6(thisArg, body) {
  * @param input.skipCommands - Top-level command names that bypass authentication entirely.
  * @param input.defaultEnvs - Built-in env presets merged underneath the user's stored env when names match.
  * @returns A yargs middleware function suitable for `.middleware([..., true])`.
+ * @__NO_SIDE_EFFECTS__
  */ function createAuthMiddleware(input) {
     var paths = buildCliPaths({
         cliName: input.cliName
@@ -5784,6 +5796,7 @@ function _ts_generator$5(thisArg, body) {
  * @param input.loadOutputConfig - Optional override for how the output config is read.
  * @param input.saveCommandOutputConfig - Optional override for how a per-command output config is persisted.
  * @returns A yargs middleware function suitable for `.middleware([..., true])`.
+ * @__NO_SIDE_EFFECTS__
  */ function createOutputMiddleware(input) {
     var _input_loadOutputConfig, _input_saveCommandOutputConfig;
     var paths = buildCliPaths({
@@ -6343,6 +6356,7 @@ function resolveCallbacks(input) {
  * @param input.mergeOutputConfig - Optional override for persisting partial output-config updates.
  * @param input.clearOutputConfig - Optional override for clearing the persisted output config entirely.
  * @returns A yargs `CommandModule` exposing the full `output` subcommand surface.
+ * @__NO_SIDE_EFFECTS__
  */ function createOutputCommand(input) {
     var callbacks = resolveCallbacks(input);
     var setCommand = {
@@ -6704,6 +6718,7 @@ function _ts_generator$2(thisArg, body) {
  * @param input.argv - Argv to parse. Defaults to `hideBin(process.argv)`.
  * @param input.disableCallPassthrough - When `true`, omits the built-in `call` passthrough.
  * @returns The configured yargs `Argv` ready to be `.parse()`-d.
+ * @__NO_SIDE_EFFECTS__
  */ function createCli(input) {
     var _input_configCommands, _input_apiCommands, _input_argv;
     var cliName = input.cliName;
@@ -7093,6 +7108,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';
@@ -7124,8 +7148,9 @@ var DATA_HELP_FLAG = '--data-help';
  * @param options - Optional overrides; see {@link BuildManifestCommandsOptions}.
  * @returns The yargs `CommandModule[]` ready to be passed to `runCli({ apiCommands })`. Empty
  *   when the manifest has no callable entries.
+ * @__NO_SIDE_EFFECTS__
  */ function buildManifestCommands(manifest, options) {
-    var _ref, _ref1, _ref2, _ref3, _ref4;
+    var _ref, _ref1, _ref2, _ref3, _ref4, _ref5;
     var callable = manifest.filter(function(e) {
         return !SKIPPED_VERBS.has(e.verb);
     });
@@ -7162,15 +7187,17 @@ var DATA_HELP_FLAG = '--data-help';
     }
     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 modelCommandName = (_ref4 = options === null || options === void 0 ? void 0 : options.modelCommandName) !== null && _ref4 !== void 0 ? _ref4 : DEFAULT_MANIFEST_MODEL_COMMAND_NAME;
+    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 [
@@ -7263,6 +7290,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>"),
@@ -7297,14 +7356,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',
@@ -7353,6 +7413,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 {
@@ -7376,37 +7442,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) {
@@ -8119,6 +8293,7 @@ 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;
@@ -8150,6 +8325,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;