@zapier/zapier-sdk-cli 0.48.1 → 0.49.0

package/dist/src/utils/parameter-resolver.js

@@ -1,4 +1,5 @@
 import inquirer from "inquirer";
+import search from "@inquirer/search";
 import chalk from "chalk";
 import ora from "ora";
 import { z } from "zod";
@@ -58,6 +59,31 @@ function getLocalResolutionOrderForParams(paramNames, resolvers) {
     }
     return order;
 }
+function unwrapSchema(schema) {
+    let current = schema;
+    while (current instanceof z.ZodOptional ||
+        current instanceof z.ZodDefault ||
+        current instanceof z.ZodNullable) {
+        current = current._zod.def.innerType;
+    }
+    return current;
+}
+function coerceToSchemaType(value, schema) {
+    if (typeof value !== "string")
+        return value;
+    const base = unwrapSchema(schema);
+    if (base instanceof z.ZodNumber) {
+        const n = Number(value);
+        return Number.isNaN(n) ? value : n;
+    }
+    if (base instanceof z.ZodBoolean) {
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+    }
+    return value;
+}
 // ============================================================================
 // Schema Parameter Resolver
 // ============================================================================
@@ -297,6 +323,290 @@ export class SchemaParameterResolver {
             throw new ZapierCliMissingParametersError(missingParams);
         }
     }
+    /**
+     * Wrap a PromptConfig.validate so internal sentinels (Symbols) bypass
+     * it. The resolver's validator is intended for actual user values; our
+     * Skip / Custom / Load-more sentinels are internal control-flow and
+     * should pass through. Returns `undefined` when the resolver didn't
+     * supply a validator (so `await search({ ...rest })` doesn't get a
+     * pass-through identity function).
+     */
+    wrapPromptValidate(validate) {
+        if (!validate)
+            return undefined;
+        return (value) => (typeof value === "symbol" ? true : validate(value));
+    }
+    /**
+     * Apply a PromptConfig.filter to a selected value, but only when the
+     * value is a real data choice (not an internal sentinel). @inquirer/search
+     * has no built-in filter hook, so the search-backed paths call this
+     * explicitly before returning.
+     */
+    applyPromptFilter(filter, value) {
+        if (!filter || typeof value === "symbol")
+            return value;
+        return filter(value);
+    }
+    /**
+     * If the resolver's PromptConfig sets a `default` value, move the
+     * matching choice to the front so it's the first selectable item in
+     * the rendered source. @inquirer/search has no built-in `default`
+     * option; first-selectable is what Enter picks, so reordering achieves
+     * the same semantics inquirer.prompt's list had natively.
+     *
+     * Returns the original array if no default is set or the default
+     * doesn't match any current choice.
+     */
+    reorderForDefault(matches, defaultValue) {
+        if (defaultValue === undefined)
+            return matches;
+        const idx = matches.findIndex((c) => c.value === defaultValue);
+        if (idx <= 0)
+            return matches;
+        return [matches[idx], ...matches.slice(0, idx), ...matches.slice(idx + 1)];
+    }
+    /**
+     * Build the disabled "if you had X capability, more results would show"
+     * hints for any unmet capabilities the resolver declared. Returns the
+     * raw hint strings — callers wrap them into choice objects with whatever
+     * sentinel value they prefer (disabled choices' values are inert).
+     */
+    async computeCapabilityHints(resolver, context) {
+        if (!resolver.requireCapabilities)
+            return [];
+        const capContext = context.sdk.context;
+        if (!capContext.hasCapability)
+            return [];
+        const messages = [];
+        for (const cap of resolver.requireCapabilities) {
+            const enabled = await capContext.hasCapability(cap);
+            if (!enabled)
+                messages.push(buildCapabilityMessage(cap));
+        }
+        return messages;
+    }
+    /**
+     * Unpack a DynamicResolver.fetch result into the three shapes the caller
+     * cares about: a flat items array, an optional AsyncIterator for further
+     * pagination, and a hasMore flag. Centralizing keeps the AsyncIterable /
+     * `{data, nextCursor}` / `TItem[]` discrimination in one place — both
+     * the main dropdown loop and the search-mode flow consume it.
+     *
+     * The function is `async` for the AsyncIterable branch only (we eagerly
+     * consume the first page so callers don't have to discriminate). The
+     * other two branches return synchronously; an explicit Promise.resolve
+     * is unnecessary because async automatically wraps.
+     *
+     * Note: callers in search mode intentionally drop `pageIterator` /
+     * `hasMore` because each search() invocation re-prompts from scratch;
+     * pagination only matters when the prompt is the dropdown itself.
+     */
+    async unpackFetchResult(fetchResult, promptLabel) {
+        if (fetchResult != null &&
+            typeof fetchResult === "object" &&
+            Symbol.asyncIterator in fetchResult) {
+            const pageIterator = fetchResult[Symbol.asyncIterator]();
+            const first = await pageIterator.next();
+            if (!first.done && first.value) {
+                return {
+                    items: Array.isArray(first.value.data) ? first.value.data : [],
+                    pageIterator,
+                    hasMore: first.value.nextCursor != null,
+                };
+            }
+            return { items: [], pageIterator, hasMore: false };
+        }
+        if (fetchResult != null &&
+            typeof fetchResult === "object" &&
+            "data" in fetchResult) {
+            const page = fetchResult;
+            const hasMore = page.nextCursor != null;
+            if (hasMore) {
+                this.debugLog(`Resolver for ${promptLabel} has more pages but no iterator. ` +
+                    `Use toIterable() to enable "Load more..." support.`);
+            }
+            return {
+                items: Array.isArray(page.data) ? page.data : [],
+                pageIterator: null,
+                hasMore,
+            };
+        }
+        // Anything else (including null/undefined) is treated as an empty
+        // list — the cast on a plain array kept downstream code happy, but
+        // an `Array.isArray` guard is the honest version.
+        return {
+            items: Array.isArray(fetchResult) ? fetchResult : [],
+            pageIterator: null,
+            hasMore: false,
+        };
+    }
+    /**
+     * Search-mode dynamic resolver: prompts the user for free-form text, passes
+     * it to fetch via `search`, and either short-circuits on a primitive return
+     * (exact match) or renders the results as a search-filterable dropdown.
+     * Empty results still render the dropdown so the user can fall through to
+     * "(Use 'foo' as-is)" or "(Try a different search)" rather than being
+     * stuck.
+     *
+     * Known limitation: pagination beyond the first page is dropped. Each
+     * search() invocation re-prompts from scratch and the user is expected
+     * to refine their query if too many results came back. If a future
+     * high-cardinality search resolver needs Load-more here, the
+     * `pageIterator` / `hasMore` from `unpackFetchResult` is what to wire in.
+     */
+    async resolveDynamicWithSearchInput({ resolver, context, promptLabel, isOptional, }) {
+        // Suffix the placeholder onto the message rather than passing it as
+        // inquirer's `default`. `inquirer`'s `input` prompt renders `default`
+        // as prefilled text the user has to delete before typing — so a user
+        // who just starts typing ends up sending `${placeholder}${typed}` as
+        // the search term. As a message suffix the hint is read-only.
+        // Fold "(optional)" and the placeholder hint into one parenthetical
+        // so an optional search prompt with a hint reads
+        // "Enter or search app (optional, e.g., 'slack'):" rather than the
+        // double-paren "Enter or search app (optional) (e.g., 'slack'):".
+        const parenParts = [];
+        if (isOptional)
+            parenParts.push("optional");
+        if (resolver.placeholder)
+            parenParts.push(resolver.placeholder);
+        const parens = parenParts.length > 0 ? ` (${parenParts.join(", ")})` : "";
+        const message = `Enter or search ${promptLabel}${parens}:`;
+        // Sentinels are loop-invariant — hoist so they aren't reallocated on
+        // every re-prompt. Identity comparisons against `selected` still work
+        // because the same Symbol references are reused.
+        const SKIP_SENTINEL = Symbol("SKIP");
+        const USE_AS_IS_SENTINEL = Symbol("USE_AS_IS");
+        const TRY_AGAIN_SENTINEL = Symbol("TRY_AGAIN");
+        let lastNote;
+        while (true) {
+            this.stopSpinner();
+            if (lastNote) {
+                console.log(chalk.yellow(lastNote));
+                lastNote = undefined;
+            }
+            const answers = await inquirer.prompt([
+                { type: "input", name: "search", message },
+            ]);
+            const rawInput = answers.search;
+            const searchInput = typeof rawInput === "string" ? rawInput.trim() : "";
+            if (!searchInput) {
+                if (isOptional)
+                    return undefined;
+                lastNote = `${promptLabel} is required.`;
+                continue;
+            }
+            // Build params once with `search` injected; pass to both fetch and
+            // prompt. The public type tells search-mode resolver authors to
+            // model TParams as `{ search?: string; ...otherDeps }`, so their
+            // prompt() can rely on seeing the term too.
+            const searchParams = {
+                ...context.resolvedParams,
+                search: searchInput,
+            };
+            this.startSpinner();
+            this.debugLog(`Searching ${promptLabel} for "${searchInput}"`);
+            let fetchResult;
+            try {
+                fetchResult = await resolver.fetch(context.sdk, searchParams);
+            }
+            finally {
+                this.stopSpinner();
+            }
+            if (typeof fetchResult === "string" || typeof fetchResult === "number") {
+                return fetchResult;
+            }
+            const { items } = await this.unpackFetchResult(fetchResult, promptLabel);
+            const choicesConfig = resolver.prompt(items, searchParams);
+            const dataChoices = choicesConfig.choices ?? [];
+            const capabilityHintMessages = await this.computeCapabilityHints(resolver, context);
+            const selected = await search({
+                message: choicesConfig.message,
+                validate: this.wrapPromptValidate(choicesConfig.validate),
+                // @inquirer/search passes an AbortSignal as the second arg for
+                // cancelling async sources. All three of our source callbacks are
+                // pure-local (filter an already-fetched array), so we intentionally
+                // ignore the signal. A future server-side filter implementation
+                // would need to honor it.
+                source: (term) => {
+                    const trimmed = (term ?? "").trim();
+                    const lower = trimmed.toLowerCase();
+                    const matches = trimmed
+                        ? dataChoices.filter((c) => c.name.toLowerCase().includes(lower))
+                        : dataChoices;
+                    // @inquirer/search activates the first selectable item, so
+                    // matches always go first — the user already typed a query at
+                    // the text prompt to get here, and pressing Enter immediately
+                    // should pick the top match rather than (Skip) or one of the
+                    // escape hatches. If the resolver's PromptConfig sets a
+                    // default, surface that match as the first selectable.
+                    const orderedMatches = trimmed
+                        ? matches
+                        : this.reorderForDefault(matches, choicesConfig.default);
+                    const skipChoice = isOptional
+                        ? [{ name: chalk.dim("(Skip)"), value: SKIP_SENTINEL }]
+                        : [];
+                    // JSON.stringify handles the quoting + escape so an input like
+                    // `foo"bar` renders as `(Use "foo\"bar" as-is)` instead of
+                    // breaking the visible label with a stray quote.
+                    const useAsIsChoice = {
+                        name: chalk.dim(`(Use ${JSON.stringify(searchInput)} as-is)`),
+                        value: USE_AS_IS_SENTINEL,
+                    };
+                    const tryAgainChoice = {
+                        name: chalk.dim("(Try a different search)"),
+                        value: TRY_AGAIN_SENTINEL,
+                    };
+                    const out = [];
+                    if (orderedMatches.length === 0) {
+                        // Empty results: the user just typed something and got
+                        // nothing back. Pushing (Skip) first would make pressing
+                        // Enter surprise-skip the parameter they committed to. Bias
+                        // toward "use what I typed" and "try a different search."
+                        out.push(useAsIsChoice);
+                        out.push(tryAgainChoice);
+                        out.push(...skipChoice);
+                    }
+                    else {
+                        out.push(...orderedMatches);
+                        out.push(...skipChoice);
+                        out.push(useAsIsChoice);
+                        out.push(tryAgainChoice);
+                    }
+                    for (const message of capabilityHintMessages) {
+                        out.push({
+                            name: chalk.dim(message),
+                            value: SKIP_SENTINEL,
+                            disabled: true,
+                        });
+                    }
+                    return out;
+                },
+            });
+            if (selected === SKIP_SENTINEL)
+                return undefined;
+            // The (Use as-is) escape hatch is a real value heading into the
+            // same downstream slot as a picked match, so the resolver's
+            // validate and filter both apply. search()'s wrapped validate
+            // bypasses sentinels, so we have to invoke validate manually here
+            // with the typed string. On rejection, surface the validator's
+            // error as a yellow note above the next text prompt.
+            if (selected === USE_AS_IS_SENTINEL) {
+                const validationResult = choicesConfig.validate?.(searchInput);
+                if (validationResult === false) {
+                    lastNote = `${promptLabel}: invalid value.`;
+                    continue;
+                }
+                if (typeof validationResult === "string") {
+                    lastNote = validationResult;
+                    continue;
+                }
+                return this.applyPromptFilter(choicesConfig.filter, searchInput);
+            }
+            if (selected === TRY_AGAIN_SENTINEL)
+                continue;
+            return this.applyPromptFilter(choicesConfig.filter, selected);
+        }
+    }
     async resolveParameter(param, context, functionName, options) {
         const resolver = this.getResolver(param.name, context.sdk, functionName);
         if (!resolver) {
@@ -306,6 +616,27 @@ export class SchemaParameterResolver {
             isOptional: options?.isOptional,
         });
     }
+    /**
+     * Run a resolver to obtain a value for one parameter, prompting the
+     * user when necessary. Routes to one of several prompt backends and
+     * has to keep the `PromptConfig` contract honest across each one.
+     *
+     * `PromptConfig` field × prompt-backend handling:
+     *
+     *  | field    | list (search()) | checkbox/confirm (inquirer.prompt) | search-mode dropdown (search()) |
+     *  | -------- | --------------- | ---------------------------------- | ------------------------------- |
+     *  | type     | required        | required                           | required                        |
+     *  | name     | (set internally)| forwarded                          | (set internally)                |
+     *  | message  | forwarded       | forwarded                          | forwarded                       |
+     *  | choices  | filtered in src | passed to inquirer                 | filtered in src                 |
+     *  | default  | reorder matches | passed (also internal cursor jump) | reorder matches                 |
+     *  | validate | wrapped         | passed (inquirer native)           | wrapped + manual for (Use as-is)|
+     *  | filter   | manual once     | inquirer native (do NOT double)    | manual once                     |
+     *
+     * Escape-hatch sentinels (Skip / Custom value / Use as-is / Load more
+     * / Try again) bypass the resolver's validate/filter because they
+     * aren't real user values — they're CLI control-flow.
+     */
     async resolveWithResolver(resolver, param, context, options = {}) {
         const { arrayIndex, isOptional } = options;
         const inArrayContext = arrayIndex != null;
@@ -338,7 +669,10 @@ export class SchemaParameterResolver {
                     value === staticResolver.placeholder)) {
                 return undefined;
             }
-            return value;
+            // Inquirer's "input" prompt always returns a string. Coerce to match
+            // the schema's underlying type so z.number()/z.boolean() validation
+            // doesn't reject the value.
+            return coerceToSchemaType(value, param.schema);
         }
         else if (resolver.type === "dynamic") {
             const dynamicResolver = resolver;
@@ -348,46 +682,55 @@ export class SchemaParameterResolver {
                 this.stopSpinner();
                 return autoResolution.resolvedValue;
             }
+            if (dynamicResolver.inputType === "search") {
+                this.stopSpinner();
+                return await this.resolveDynamicWithSearchInput({
+                    resolver: dynamicResolver,
+                    context,
+                    promptLabel,
+                    isOptional: isOptional ?? false,
+                });
+            }
             this.debugLog(`Fetching options for ${promptLabel}`);
-            const fetchResult = await dynamicResolver.fetch(context.sdk, context.resolvedParams);
-            // Check if the result is an AsyncIterable of pages (from toIterable())
-            let pageIterator = null;
-            let items;
-            let hasMore = false;
-            if (fetchResult != null &&
-                typeof fetchResult === "object" &&
-                Symbol.asyncIterator in fetchResult) {
-                // Paginated: pull the first page from the iterator
-                pageIterator = fetchResult[Symbol.asyncIterator]();
-                const first = await pageIterator.next();
-                if (!first.done && first.value) {
-                    items = first.value.data;
-                    hasMore = first.value.nextCursor != null;
-                }
-                else {
-                    items = [];
-                }
+            let fetchResult;
+            try {
+                fetchResult = await dynamicResolver.fetch(context.sdk, context.resolvedParams);
             }
-            else if (fetchResult != null &&
-                typeof fetchResult === "object" &&
-                "data" in fetchResult) {
-                const page = fetchResult;
-                items = page.data;
-                hasMore = page.nextCursor != null;
-                if (hasMore) {
-                    this.debugLog(`Resolver for ${promptLabel} has more pages but no iterator. ` +
-                        `Use toIterable() to enable "Load more..." support.`);
-                }
+            finally {
+                // Mirror the search-mode pattern: stop the spinner whether fetch
+                // succeeds or throws, so a network/auth error doesn't leave the
+                // spinner spinning through the error bubbling.
+                this.stopSpinner();
             }
-            else {
-                items = fetchResult || [];
-                pageIterator = null;
+            // Primitive returns are only meaningful in `inputType: "search"`
+            // mode, where they signal an exact-match short-circuit. Without
+            // search mode there's nothing for the user to disambiguate, so a
+            // primitive here is a resolver bug. Warn the author loudly, then fall
+            // back to a manual text prompt so the user isn't stranded mid-command.
+            if (typeof fetchResult === "string" || typeof fetchResult === "number") {
+                console.error(chalk.yellow(`Resolver for ${promptLabel} returned a primitive value but is not in search mode. Set inputType: "search" on the resolver if you want exact-match short-circuit. Falling back to manual entry.`));
+                const fallbackAnswers = await inquirer.prompt([
+                    {
+                        type: "input",
+                        name: promptName,
+                        message: `Enter ${promptLabel}${isOptional ? " (optional)" : ""}:`,
+                    },
+                ]);
+                const fallbackValue = fallbackAnswers[promptName];
+                if (isOptional &&
+                    (fallbackValue === undefined || fallbackValue === "")) {
+                    return undefined;
+                }
+                return fallbackValue;
             }
+            const unpacked = await this.unpackFetchResult(fetchResult, promptLabel);
+            let pageIterator = unpacked.pageIterator;
+            let items = unpacked.items;
+            let hasMore = unpacked.hasMore;
             const LOAD_MORE_SENTINEL = Symbol("LOAD_MORE");
             const SKIP_SENTINEL = Symbol("SKIP");
             const CUSTOM_VALUE_SENTINEL = Symbol("CUSTOM_VALUE");
             let newItemsStartIndex = -1;
-            this.stopSpinner();
             while (true) {
                 const promptConfig = dynamicResolver.prompt(items, context.resolvedParams);
                 promptConfig.name = promptName;
@@ -400,59 +743,134 @@ export class SchemaParameterResolver {
                 if (!hasSelectableChoice && !hasMore) {
                     throw new ZapierCliValidationError(`No ${promptLabel} available to select.`);
                 }
-                if (isOptional && promptConfig.choices) {
-                    promptConfig.choices.unshift({
-                        name: chalk.dim("(Skip)"),
-                        value: SKIP_SENTINEL,
-                    });
-                }
-                // Pinned to the top so it's reachable without scrolling past a long
-                // list. Restricted to single-select: a typed scalar can't merge
-                // sensibly with checkbox selections.
-                if (promptConfig.choices && promptConfig.type === "list") {
-                    const insertAt = isOptional ? 1 : 0;
-                    promptConfig.choices.splice(insertAt, 0, {
-                        name: chalk.dim("(Enter custom value)"),
-                        value: CUSTOM_VALUE_SENTINEL,
-                    });
+                // Capability hints: shown when no more pages remain and the
+                // resolver advertised capabilities that would expand results.
+                // The Skip / (Enter custom value) / (Load more...) sentinels live
+                // in the list/checkbox branches below since the search-backed list
+                // path injects them via the source callback rather than mutating
+                // promptConfig.choices.
+                const capabilityHints = [];
+                if (!hasMore) {
+                    const hintMessages = await this.computeCapabilityHints(dynamicResolver, context);
+                    for (const message of hintMessages) {
+                        capabilityHints.push({
+                            name: chalk.dim(message),
+                            value: SKIP_SENTINEL,
+                            disabled: true,
+                        });
+                    }
                 }
-                // Add "Load more..." option if paginated
-                if (hasMore && pageIterator && promptConfig.choices) {
-                    promptConfig.choices.push({
-                        name: chalk.dim("(Load more...)"),
-                        value: LOAD_MORE_SENTINEL,
+                let selected;
+                if (promptConfig.type === "list") {
+                    // Single-select dropdowns go through @inquirer/search so users
+                    // can type-to-filter long lists. (Load more...) sits as a trailer
+                    // and is reachable whether or not the search yielded matches; the
+                    // user retypes after loading because @inquirer/search can't seed
+                    // its input box.
+                    const dataChoices = promptConfig.choices ?? [];
+                    selected = await search({
+                        message: promptConfig.message,
+                        validate: this.wrapPromptValidate(promptConfig.validate),
+                        source: (term) => {
+                            const trimmed = (term ?? "").trim();
+                            const lower = trimmed.toLowerCase();
+                            const matches = trimmed
+                                ? dataChoices.filter((c) => c.name.toLowerCase().includes(lower))
+                                : dataChoices;
+                            const out = [];
+                            const skipChoice = isOptional
+                                ? [
+                                    {
+                                        name: chalk.dim("(Skip)"),
+                                        value: SKIP_SENTINEL,
+                                    },
+                                ]
+                                : [];
+                            const customValueChoice = {
+                                name: chalk.dim("(Enter custom value)"),
+                                value: CUSTOM_VALUE_SENTINEL,
+                            };
+                            // @inquirer/search activates the first selectable item.
+                            // Three cases, with one unifying rule: never put (Skip)
+                            // first when the user is committed (typed a filter,
+                            // default specified) — pressing Enter then surprise-skips.
+                            // - Has matches + (filtered or defaulted) → matches first,
+                            //   then Skip and Custom, then Load more as a trailer.
+                            // - No matches + filtered → Custom and Load more above
+                            //   Skip, so every constructive option beats out skipping.
+                            // - Otherwise (browsing) → Skip first (the conventional
+                            //   optional-dropdown UX), then Custom, matches, Load more.
+                            const orderedMatches = trimmed
+                                ? matches
+                                : this.reorderForDefault(matches, promptConfig.default);
+                            const matchesFirst = trimmed || promptConfig.default !== undefined;
+                            const loadMoreChoice = hasMore && pageIterator
+                                ? {
+                                    name: chalk.dim("(Load more...)"),
+                                    value: LOAD_MORE_SENTINEL,
+                                }
+                                : null;
+                            if (matchesFirst && orderedMatches.length > 0) {
+                                out.push(...orderedMatches);
+                                out.push(...skipChoice);
+                                out.push(customValueChoice);
+                                if (loadMoreChoice)
+                                    out.push(loadMoreChoice);
+                            }
+                            else if (matchesFirst) {
+                                out.push(customValueChoice);
+                                if (loadMoreChoice)
+                                    out.push(loadMoreChoice);
+                                out.push(...skipChoice);
+                            }
+                            else {
+                                out.push(...skipChoice);
+                                out.push(customValueChoice);
+                                out.push(...orderedMatches);
+                                if (loadMoreChoice)
+                                    out.push(loadMoreChoice);
+                            }
+                            // Capability hints only render when there are actual matches
+                            // (or no search term) so an empty-search view stays focused.
+                            if (capabilityHints.length > 0 &&
+                                (!trimmed || matches.length > 0)) {
+                                out.push(...capabilityHints);
+                            }
+                            return out;
+                        },
                     });
                 }
-                // Show hints for capabilities that would expand results
-                if (!hasMore &&
-                    promptConfig.choices &&
-                    dynamicResolver.requireCapabilities) {
-                    const capContext = context.sdk.context;
-                    if (capContext.hasCapability) {
-                        for (const cap of dynamicResolver.requireCapabilities) {
-                            const enabled = await capContext.hasCapability(cap);
-                            if (!enabled) {
-                                promptConfig.choices.push({
-                                    name: chalk.dim(buildCapabilityMessage(cap)),
-                                    value: SKIP_SENTINEL,
-                                    disabled: true,
-                                });
-                            }
-                        }
+                else {
+                    // Multi-select (checkbox) and confirm prompts stay on
+                    // inquirer.prompt — search is single-select.
+                    if (isOptional && promptConfig.choices) {
+                        promptConfig.choices.unshift({
+                            name: chalk.dim("(Skip)"),
+                            value: SKIP_SENTINEL,
+                        });
                     }
-                }
-                // After loading more, jump cursor to first new item.
-                // Offset by the number of injected choices before the data items (e.g. Skip).
-                if (newItemsStartIndex >= 0 && promptConfig.choices) {
-                    const injectedBefore = (isOptional ? 1 : 0) + (promptConfig.type === "list" ? 1 : 0);
-                    const adjustedIndex = newItemsStartIndex + injectedBefore;
-                    if (promptConfig.choices[adjustedIndex]) {
-                        promptConfig.default = promptConfig.choices[adjustedIndex].value;
+                    if (hasMore && pageIterator && promptConfig.choices) {
+                        promptConfig.choices.push({
+                            name: chalk.dim("(Load more...)"),
+                            value: LOAD_MORE_SENTINEL,
+                        });
+                    }
+                    if (capabilityHints.length > 0 && promptConfig.choices) {
+                        promptConfig.choices.push(...capabilityHints);
                     }
-                    newItemsStartIndex = -1;
+                    // After loading more, jump cursor to first new item.
+                    // Offset by the number of injected choices before the data items (e.g. Skip).
+                    if (newItemsStartIndex >= 0 && promptConfig.choices) {
+                        const injectedBefore = isOptional ? 1 : 0;
+                        const adjustedIndex = newItemsStartIndex + injectedBefore;
+                        if (promptConfig.choices[adjustedIndex]) {
+                            promptConfig.default = promptConfig.choices[adjustedIndex].value;
+                        }
+                        newItemsStartIndex = -1;
+                    }
+                    const answers = await inquirer.prompt([promptConfig]);
+                    selected = answers[promptName];
                 }
-                const answers = await inquirer.prompt([promptConfig]);
-                let selected = answers[promptName];
                 if (selected === SKIP_SENTINEL) {
                     return undefined;
                 }
@@ -492,7 +910,14 @@ export class SchemaParameterResolver {
                     }
                     continue;
                 }
-                return selected;
+                // Only the search-backed list path needs a manual filter call —
+                // @inquirer/search has no built-in filter hook. inquirer.prompt
+                // (the checkbox / confirm branch above) already applies the
+                // resolver's filter natively, so re-applying here would
+                // double-filter non-idempotent values.
+                return promptConfig.type === "list"
+                    ? this.applyPromptFilter(promptConfig.filter, selected)
+                    : selected;
             }
         }
         else if (resolver.type === "fields") {
@@ -794,74 +1219,122 @@ export class SchemaParameterResolver {
         }
     }
     /**
-     * Prompt user with choices (handles both single and multi-select with pagination)
+     * Prompt user with choices (handles both single and multi-select with pagination).
+     * Single-select goes through @inquirer/search so users can type-to-filter long
+     * dropdowns (SELECT fields); multi-select stays on inquirer.prompt since search
+     * is single-select only.
      */
     async promptWithChoices({ fieldMeta, choices: initialChoices, nextCursor: initialCursor, inputs, context, }) {
         this.stopSpinner();
         const choices = [...initialChoices];
         let nextCursor = initialCursor;
         const LOAD_MORE_SENTINEL = Symbol("LOAD_MORE");
+        const SKIP_SENTINEL = Symbol("SKIP");
         const CUSTOM_VALUE_SENTINEL = Symbol("CUSTOM_VALUE");
-        // Progressive loading loop
+        const message = `${fieldMeta.title}${fieldMeta.isRequired ? " (required)" : " (optional)"}:`;
         while (true) {
-            const promptChoices = choices.map((choice) => ({
-                name: choice.label,
-                value: choice.value,
-            }));
-            // Pin "(Enter custom value)" to the top for single-select fields so
-            // users can supply values not in the fetched dropdown (e.g. dynamic
-            // dropdowns that don't return every valid value).
+            let selectedValue;
             if (!fieldMeta.isMultiSelect) {
-                promptChoices.unshift({
-                    name: chalk.dim("(Enter custom value)"),
-                    value: CUSTOM_VALUE_SENTINEL,
-                });
-            }
-            // Add "(Load more...)" option if there are more pages
-            if (nextCursor) {
-                promptChoices.push({
-                    name: chalk.dim("(Load more...)"),
-                    value: LOAD_MORE_SENTINEL,
+                const dataChoices = choices.map((c) => ({
+                    name: c.label,
+                    value: c.value,
+                }));
+                selectedValue = await search({
+                    message,
+                    source: (term) => {
+                        const trimmed = (term ?? "").trim();
+                        const lower = trimmed.toLowerCase();
+                        const matches = trimmed
+                            ? dataChoices.filter((c) => c.name.toLowerCase().includes(lower))
+                            : dataChoices;
+                        const out = [];
+                        const skipChoice = !fieldMeta.isRequired
+                            ? [{ name: chalk.dim("(Skip)"), value: SKIP_SENTINEL }]
+                            : [];
+                        // Dynamic dropdowns don't always return every valid value, so a
+                        // custom-value escape hatch is essential for SELECT fields.
+                        const customValueChoice = {
+                            name: chalk.dim("(Enter custom value)"),
+                            value: CUSTOM_VALUE_SENTINEL,
+                        };
+                        // Same ordering rule as the main dynamic-list source: never
+                        // let (Skip) be the first selectable when the user is
+                        // committed (filtered). Empty filtered results put Custom
+                        // and Load more above Skip so every constructive option
+                        // beats out skipping. Otherwise matches go first.
+                        const loadMoreChoice = nextCursor && context
+                            ? {
+                                name: chalk.dim("(Load more...)"),
+                                value: LOAD_MORE_SENTINEL,
+                            }
+                            : null;
+                        if (trimmed && matches.length > 0) {
+                            out.push(...matches);
+                            out.push(...skipChoice);
+                            out.push(customValueChoice);
+                            if (loadMoreChoice)
+                                out.push(loadMoreChoice);
+                        }
+                        else if (trimmed) {
+                            out.push(customValueChoice);
+                            if (loadMoreChoice)
+                                out.push(loadMoreChoice);
+                            out.push(...skipChoice);
+                        }
+                        else {
+                            out.push(...skipChoice);
+                            out.push(customValueChoice);
+                            out.push(...matches);
+                            if (loadMoreChoice)
+                                out.push(loadMoreChoice);
+                        }
+                        return out;
+                    },
                 });
+                if (selectedValue === SKIP_SENTINEL) {
+                    return undefined;
+                }
+                if (selectedValue === CUSTOM_VALUE_SENTINEL) {
+                    return await this.promptFreeForm(fieldMeta);
+                }
             }
-            // Add skip option for optional fields (single-select only)
-            if (!fieldMeta.isRequired && !fieldMeta.isMultiSelect) {
-                promptChoices.push({ name: "(Skip)", value: undefined });
-            }
-            const promptConfig = {
-                type: fieldMeta.isMultiSelect ? "checkbox" : "list",
-                name: fieldMeta.key,
-                message: `${fieldMeta.title}${fieldMeta.isRequired ? " (required)" : " (optional)"}:`,
-                choices: promptChoices,
-                ...(fieldMeta.isMultiSelect && {
+            else {
+                const promptChoices = choices.map((c) => ({
+                    name: c.label,
+                    value: c.value,
+                }));
+                if (nextCursor) {
+                    promptChoices.push({
+                        name: chalk.dim("(Load more...)"),
+                        value: LOAD_MORE_SENTINEL,
+                    });
+                }
+                const promptConfig = {
+                    type: "checkbox",
+                    name: fieldMeta.key,
+                    message,
+                    choices: promptChoices,
                     validate: (input) => {
                         if (fieldMeta.isRequired && (!input || input.length === 0)) {
                             return "At least one selection is required";
                         }
                         return true;
                     },
-                }),
-            };
-            const answer = await inquirer.prompt([promptConfig]);
-            let selectedValue = answer[fieldMeta.key];
-            if (selectedValue === CUSTOM_VALUE_SENTINEL) {
-                return await this.promptFreeForm(fieldMeta);
+                };
+                const answer = await inquirer.prompt([promptConfig]);
+                selectedValue = answer[fieldMeta.key];
             }
-            // Check if user selected "Load more..."
             const wantsMore = fieldMeta.isMultiSelect
                 ? Array.isArray(selectedValue) &&
                     selectedValue.includes(LOAD_MORE_SENTINEL)
                 : selectedValue === LOAD_MORE_SENTINEL;
             if (wantsMore && nextCursor && context) {
-                // Remove sentinel from multi-select
                 if (fieldMeta.isMultiSelect && Array.isArray(selectedValue)) {
                     selectedValue = selectedValue.filter((v) => v !== LOAD_MORE_SENTINEL);
                 }
-                // Fetch next page
                 const result = await this.fetchChoices(fieldMeta, inputs, context, nextCursor);
                 choices.push(...result.choices);
                 nextCursor = result.nextCursor;
-                // Re-prompt with updated choices
                 continue;
             }
             return selectedValue;