@sanity/workflow-cli 0.20.0 → 0.22.0

package/dist/commands/editorial-workflows/show.js

@@ -4,7 +4,7 @@ import { abortReason, displayTitle, terminalState, } from '@sanity/workflow-engi
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { findInstance, resolveReadTargets } from "../../lib/context.js";
-import { tagFlags } from "../../lib/flags.js";
+import { jsonFlags, tagFlags } from "../../lib/flags.js";
 import { formatKeyValue, formatTimestamp, sectionHeader, activityIcon } from "../../lib/ui.js";
 export default class Show extends WorkflowCommand {
     static aliases = ['show'];
@@ -12,6 +12,7 @@ export default class Show extends WorkflowCommand {
     static examples = [
         '<%= config.bin %> show wf-instance.abc123',
         '<%= config.bin %> show wf-instance.abc123 --include history',
+        '<%= config.bin %> show wf-instance.abc123 --json',
     ];
     static args = {
         instanceId: Args.string({
@@ -22,11 +23,12 @@ export default class Show extends WorkflowCommand {
     static flags = {
         ...tagFlags,
         include: Flags.string({
-            description: 'Optional sections to include in output.',
+            description: 'Optional sections to include in rendered output (--json always carries the full document).',
             options: ['history'],
             multiple: true,
             default: [],
         }),
+        ...jsonFlags,
     };
     async run() {
         const { args, flags } = await this.parse(Show);
@@ -36,6 +38,10 @@ export default class Show extends WorkflowCommand {
             this.error(`${logSymbols.error} no instance with id "${args.instanceId}"`, { exit: 1 });
         }
         const { instance } = hit;
+        if (flags.json) {
+            this.log(JSON.stringify(instance, null, 2));
+            return;
+        }
         this.log(instanceHeader(instance));
         this.log('');
         for (const line of describeInstance(instance, {
@@ -55,14 +61,16 @@ export function instanceHeader(instance) {
     if (terminalState(instance) === 'aborted' && instance.abortedAt !== undefined) {
         const reason = abortReason(instance);
         const tail = reason ? ` — ${reason}` : '';
-        const value = styleText('yellow', `${formatTimestamp(instance.abortedAt)}${tail}`);
-        rows.push(formatKeyValue({ key: 'Aborted', value, padTo: HEADER_PAD }));
+        const value = `${formatTimestamp(instance.abortedAt)}${tail}`;
+        rows.push(formatKeyValue({ key: 'Aborted', value, padTo: HEADER_PAD, emphasis: 'yellow' }));
+    }
+    else if (instance.completedAt) {
+        const value = formatTimestamp(instance.completedAt);
+        rows.push(formatKeyValue({ key: 'Completed', value, padTo: HEADER_PAD, emphasis: 'green' }));
     }
     else {
-        const completed = instance.completedAt
-            ? styleText('green', formatTimestamp(instance.completedAt))
-            : styleText('dim', '—');
-        rows.push(formatKeyValue({ key: 'Completed', value: completed, padTo: HEADER_PAD }));
+        const value = styleText('dim', '—');
+        rows.push(formatKeyValue({ key: 'Completed', value, padTo: HEADER_PAD }));
     }
     rows.push(formatKeyValue({ key: 'Tag', value: instance.tag, padTo: HEADER_PAD }));
     return [title, ...rows].join('\n');

package/dist/help.d.ts

@@ -0,0 +1,8 @@
+import { Help } from '@oclif/core';
+export declare const isBareSurface: (idOrName: string) => boolean;
+export declare const keepCommandAtRoot: (id: string) => boolean;
+/** Standalone-binary help that lists the nested `definition` commands flat in
+ *  `--help` rather than under a topic. A mounted host governs its own root help. */
+export default class WorkflowHelp extends Help {
+    protected showRootHelp(): Promise<void>;
+}

package/dist/help.js

@@ -0,0 +1,23 @@
+import { Help } from '@oclif/core';
+export const isBareSurface = (idOrName) => !idOrName.startsWith('editorial-workflows');
+export const keepCommandAtRoot = (id) => id !== '' && isBareSurface(id);
+export default class WorkflowHelp extends Help {
+    async showRootHelp() {
+        if (this.opts.all) {
+            await super.showRootHelp();
+            return;
+        }
+        this.log(this.formatRoot());
+        this.log('');
+        const topics = this.sortedTopics.filter((topic) => isBareSurface(topic.name));
+        if (topics.length > 0) {
+            this.log(this.formatTopics(topics));
+            this.log('');
+        }
+        const commands = this.sortedCommands.filter((command) => keepCommandAtRoot(command.id));
+        if (commands.length > 0) {
+            this.log(this.formatCommands(commands));
+            this.log('');
+        }
+    }
+}

package/dist/lib/context.d.ts

@@ -1,7 +1,6 @@
 import type { SanityClient } from '@sanity/client';
 import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import type { EngineScope } from './operation-args.ts';
-import { type ChooseDeploymentName } from './select-deployment.ts';
 export interface DeploymentContext {
     deployment: WorkflowDeployment;
     client: SanityClient;
@@ -51,20 +50,18 @@ export declare function dedupeResources(resources: WorkflowResource[]): Workflow
  *  tag (tags may repeat across deployments), or — untagged — every distinct
  *  one the config's deployments mention ({@link dedupeResources}). */
 export declare function resolveReadResources(config: WorkflowConfig, tag: string | undefined): WorkflowResource[];
-/** The single resource an instance-keyed command reads from when it isn't
- *  disambiguated interactively: the sole resource, the `--tag`-narrowed one, or
- *  a `fail` asking for `--deployment`/`--tag` when the config spans several. The
- *  interactive picker lives in {@link resolveInstanceResource}; listings fan out
- *  via {@link resolveReadResources} instead. */
-export declare function resolveReadResource(config: WorkflowConfig, tag: string | undefined): WorkflowResource;
 /**
- * The resolution an instance-id-targeted command shares, read or write: an
- * authenticated client for the resource, plus the instance itself — so the
- * command derives its partition (`tag`) from the instance, never from the
- * config's declared deployments. An instance id is globally unique and carries
- * its own `tag`, so a command that names one acts on that instance regardless
- * of which tags the config happens to deploy; the config only locates the
- * resource (via {@link resolveInstanceResource}, no tag filter).
+ * The resolution an instance-id-targeted command shares, read or write: locate
+ * the instance by the same cross-resource fan-out the read/list commands use
+ * ({@link findInstance}), then hand back an authenticated client for the
+ * resource that held it plus a scope whose `tag` comes from the instance
+ * itself — never from the config's declared deployments. An instance id is
+ * globally unique and carries its own `tag`, so naming one is enough to act on
+ * it: the config only locates candidate resources, and the fan-out's
+ * {@link soleHitOrFail} rejects the collision case where several datasets hold
+ * the id (the `<tag>.` fast-path may skip that full-set check — safe, ids are
+ * collision-free). `--deployment` / `--tag` stay optional narrowers, not
+ * required disambiguators.
  *
  * Contrast {@link resolveContext}: the deploy/diff/delete path IS scoped to a
  * declared deployment because it acts on the authored definition set (or a
@@ -74,29 +71,6 @@ export declare function resolveInstanceContext(flags: {
     deployment?: string | undefined;
     tag?: string | undefined;
 }, instanceId: string): Promise<InstanceContext>;
-/**
- * Which resource an instance-keyed command reads from: the one `--deployment`
- * names (resolved by its unique deployment name); otherwise, when the config
- * spans several resources, an interactive terminal is prompted to pick a
- * deployment ({@link canPromptOnStderr}) — its resource is the read source, the
- * interactive counterpart to `--deployment`. A run that can't prompt falls to
- * the sole or `--tag`-narrowed resource, or the ambiguity error
- * ({@link resolveReadResource}). The instance id is globally unique, so this
- * only locates the resource to look in — never the instance's `tag` partition,
- * which the caller takes from the loaded instance. The shared path behind all
- * four instance-keyed commands.
- */
-export declare function resolveInstanceResource(config: WorkflowConfig, { deployment, tag, interactive, chooseDeployment, }: {
-    deployment?: string | undefined;
-    tag?: string | undefined;
-    interactive?: boolean | undefined;
-    chooseDeployment?: ChooseDeploymentName | undefined;
-}): Promise<WorkflowResource>;
-/** Fetch an instance by id, exiting cleanly when the resource has no such
- *  document — the diagnostic an operator sees on a mistyped id. Split out from
- *  {@link resolveInstanceContext} so the not-found path is unit-testable
- *  without a live config/token/client. */
-export declare function loadInstanceOrFail(client: Pick<SanityClient, 'getDocument'>, instanceId: string): Promise<WorkflowInstance>;
 /** A read target that turned out to hold the instance being looked up. */
 export interface InstanceHit extends ReadTarget {
     instance: WorkflowInstance;

package/dist/lib/context.js

@@ -2,19 +2,20 @@ import { assertReadableModel, resourceGdr, } from '@sanity/workflow-engine';
 import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
-import { canPromptOnStderr } from "./prompt.js";
-import { availableDeployments, deploymentsForTag, selectDeployment, } from "./select-deployment.js";
+import { deploymentsForTag, selectDeployment } from "./select-deployment.js";
 import { resourceLabel } from "./ui.js";
 export async function resolveContext(flags) {
     const config = await loadWorkflowConfig();
     const deployment = await selectDeployment(config, { name: flags.deployment, tag: flags.tag });
     return { deployment, client: clientFor(deployment.workflowResource, await resolveTokenOrFail()) };
 }
+function targetsFor(resources, token) {
+    return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
+}
 export async function resolveReadTargets(flags) {
     const config = await loadWorkflowConfig();
     const resources = resolveReadResources(config, flags.tag);
-    const token = await resolveTokenOrFail();
-    return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
+    return targetsFor(resources, await resolveTokenOrFail());
 }
 export function dedupeResources(resources) {
     return [...new Map(resources.map((resource) => [resourceGdr(resource), resource])).values()];
@@ -29,50 +30,53 @@ export function resolveReadResources(config, tag) {
     }
     return resources;
 }
-export function resolveReadResource(config, tag) {
-    const resources = resolveReadResources(config, tag);
-    const [sole] = resources;
-    if (resources.length === 1 && sole !== undefined) {
-        return sole;
+const LOCATE_TAG = 'instance.load';
+export async function resolveInstanceContext(flags, instanceId) {
+    const config = await loadWorkflowConfig();
+    const token = await resolveTokenOrFail();
+    const hit = await locateInstance({ config, flags, instanceId, token });
+    if (hit === undefined) {
+        fail(`Workflow instance ${instanceId} not found`);
     }
-    if (tag === undefined) {
-        fail('Config spans multiple resources — pass --deployment or --tag to choose one.', availableDeployments(config));
+    return { client: hit.client, scope: { tag: hit.instance.tag, workflowResource: hit.resource } };
+}
+async function locateInstance({ config, flags, instanceId, token, }) {
+    const resources = await instanceCandidateResources(config, flags);
+    const fanOut = () => findInstance({ targets: targetsFor(resources, token), instanceId, requestTag: LOCATE_TAG });
+    const explicit = flags.deployment !== undefined || flags.tag !== undefined;
+    const hinted = explicit || resources.length <= 1
+        ? []
+        : hintedResources({ config, instanceId, candidates: resources });
+    if (hinted.length === 0 || hinted.length === resources.length) {
+        return fanOut();
     }
-    const carriers = config.deployments.filter((d) => d.tag === tag);
-    fail(`Tag "${tag}" spans multiple resources — pass --deployment to choose one.`, availableDeployments(config, carriers));
+    const hit = await hintedProbe(targetsFor(hinted, token), instanceId);
+    return hit ?? fanOut();
 }
-export async function resolveInstanceContext(flags, instanceId) {
-    const config = await loadWorkflowConfig();
-    const workflowResource = await resolveInstanceResource(config, flags);
-    const client = clientFor(workflowResource, await resolveTokenOrFail());
-    const instance = await loadInstanceOrFail(client, instanceId);
-    return { client, scope: { tag: instance.tag, workflowResource } };
+async function hintedProbe(targets, instanceId) {
+    try {
+        return await findInstance({ targets, instanceId, requestTag: LOCATE_TAG });
+    }
+    catch {
+        return undefined;
+    }
 }
-export async function resolveInstanceResource(config, { deployment, tag, interactive, chooseDeployment, }) {
+async function instanceCandidateResources(config, { deployment, tag }) {
     if (deployment !== undefined) {
-        return (await selectDeployment(config, { name: deployment, tag: undefined })).workflowResource;
-    }
-    if (tag === undefined &&
-        (interactive ?? canPromptOnStderr()) &&
-        resolveReadResources(config, undefined).length > 1) {
-        const chosen = await selectDeployment(config, {
-            name: undefined,
-            tag: undefined,
-            interactive: true,
-            chooseName: chooseDeployment,
-        });
-        return chosen.workflowResource;
+        return [(await selectDeployment(config, { name: deployment, tag: undefined })).workflowResource];
     }
-    return resolveReadResource(config, tag);
+    return resolveReadResources(config, tag);
 }
-export async function loadInstanceOrFail(client, instanceId) {
-    const instance = await client.getDocument(instanceId, {
-        tag: 'instance.load',
-    });
-    if (!instance) {
-        fail(`Workflow instance ${instanceId} not found`);
+function hintedResources({ config, instanceId, candidates, }) {
+    const dot = instanceId.indexOf('.');
+    if (dot <= 0) {
+        return [];
     }
-    return assertReadableModel(instance);
+    const prefix = instanceId.slice(0, dot);
+    const taggedGdrs = new Set(config.deployments
+        .filter((deployment) => deployment.tag === prefix)
+        .map((deployment) => resourceGdr(deployment.workflowResource)));
+    return candidates.filter((resource) => taggedGdrs.has(resourceGdr(resource)));
 }
 export function soleHitOrFail(hits, subject) {
     const [sole, ...rest] = hits;

package/dist/lib/fail.js

@@ -8,7 +8,7 @@ export function fail(headline, detail) {
     process.stderr.write(`${styleText('red', `${logSymbols.error} ${headline}`)}\n`);
     if (detail !== undefined && detail !== '') {
         for (const line of detail.split('\n')) {
-            process.stderr.write(`  ${styleText('red', line)}\n`);
+            process.stderr.write(`  ${line}\n`);
         }
     }
     return Errors.exit(1);

package/dist/lib/flags.d.ts

@@ -7,13 +7,13 @@
 export declare const tagFlags: {
     tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
-/** The selectors an instance-keyed command (`diagnose`, `abort`, `set-stage`,
- *  `fire-action`) takes. An instance id is globally unique and carries its own
- *  `tag`, so these only pick WHICH resource to read it from — never the
- *  instance's partition, which always comes from the loaded instance.
- *  `--deployment` names one deployment and reads from the resource it targets;
- *  `--tag` stays the optional narrower {@link tagFlags} describes. Mutually
- *  exclusive; a sole-resource config needs neither. */
+/** The optional narrowers an instance-keyed command (`diagnose`, `abort`,
+ *  `set-stage`, `fire-action`, `reset-activity`) takes. The command locates the
+ *  instance by fanning out across every configured resource, so neither is ever
+ *  required — an instance id is globally unique and carries its own `tag`. They
+ *  only narrow WHERE to look: `--deployment` to the resource one deployment
+ *  targets, `--tag` to the resources under that tag. The instance's partition
+ *  always comes from the loaded instance, never from these. Mutually exclusive. */
 export declare const instanceFlags: {
     deployment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -28,6 +28,11 @@ export declare const deploymentFlags: {
     deployment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
+/** Structured stdout instead of the rendered view. One payload convention:
+ *  verb commands emit their operation envelope (`instanceId` carries the doc
+ *  `_id`); read commands emit document-shaped data — `show` commands print
+ *  the fetched document as stored, list commands print the table's row view
+ *  (plus each row's `resource`) under a `truncated` flag. */
 export declare const jsonFlags: {
     json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };

package/dist/lib/flags.js

@@ -1,11 +1,11 @@
 import { Flags } from '@oclif/core';
-const tagAsFilterDescription = 'Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.';
+const tagAsFilterDescription = 'Workflow environment tag (e.g. prod, test) — an optional query filter that also narrows which resources are searched; omit to span them all.';
 export const tagFlags = {
     tag: Flags.string({ description: tagAsFilterDescription }),
 };
 export const instanceFlags = {
     deployment: Flags.string({
-        description: 'Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.',
+        description: 'Deployment name — narrow the instance search to the resource that deployment targets; the tag partition still comes from the loaded instance.',
         exclusive: ['tag'],
     }),
     tag: Flags.string({ description: tagAsFilterDescription, exclusive: ['deployment'] }),

package/dist/lib/read-fanout.d.ts

@@ -6,6 +6,29 @@ export interface ReadFailure {
     resource: WorkflowResource;
     message: string;
 }
+/**
+ * The `--json` tail of a list command — the structured counterpart of
+ * {@link runReadAcrossTargets} + the clipped table: fetch every target's
+ * rows, {@link clipToLimit} each target's page, map rows through the
+ * command's row view (`toRow`, the structured analogue of the table's
+ * `toCells`), annotate each with the resource it came from (the analogue of
+ * the banner), and log one `{<key>: rows, truncated}` payload.
+ * All-or-nothing, unlike the human path's per-resource tolerance: a script
+ * would mistake a listing that silently omitted an unreadable resource for
+ * the complete result, so any failure rejects the whole read.
+ */
+export declare function logJsonListing<T, R>({ targets, fetch, toRow, key, limit, log, }: {
+    targets: ReadTarget[];
+    fetch: (target: ReadTarget) => Promise<{
+        rows: T[];
+        hasMore: boolean;
+    }>;
+    toRow: (row: T) => R;
+    /** The payload's row key — names what the rows are (`instances`, `definitions`). */
+    key: string;
+    limit: number;
+    log: (line: string) => void;
+}): Promise<void>;
 /**
  * Run a read over every target, grouping output per resource: a banner when
  * the read spans several, then whatever `run` logs for that target. A throw

package/dist/lib/read-fanout.js

@@ -1,6 +1,22 @@
 import logSymbols from 'log-symbols';
 import { failureDetail } from "./fail.js";
-import { groupBanner, resourceLabel } from "./ui.js";
+import { clipToLimit, groupBanner, resourceLabel } from "./ui.js";
+export async function logJsonListing({ targets, fetch, toRow, key, limit, log, }) {
+    const fetched = await Promise.all(targets.map(async (target) => {
+        const { rows, hasMore } = await fetch(target);
+        return {
+            rows: clipToLimit(rows, limit).rows.map((row) => ({
+                ...toRow(row),
+                resource: target.resource,
+            })),
+            hasMore: hasMore || rows.length > limit,
+        };
+    }));
+    log(JSON.stringify({
+        [key]: fetched.flatMap((result) => result.rows),
+        truncated: fetched.some((result) => result.hasMore),
+    }, null, 2));
+}
 export async function runReadAcrossTargets({ targets, log, run, }) {
     const failures = [];
     for (const [index, target] of targets.entries()) {

package/dist/lib/select-deployment.d.ts

@@ -48,10 +48,6 @@ export declare function deploymentsForTag(config: WorkflowConfig, tag: string):
  * explicit opt-in — never a default.
  */
 export declare function selectDeployments(config: WorkflowConfig, { name, tag, allTags, interactive, chooseName }: DeploymentSelectionOptions): Promise<WorkflowDeployment[]>;
-/** The "Available deployments: name (tag), …" hint every ambiguity failure
- *  prints — one vocabulary across the write and instance-keyed paths, so a
- *  reader always sees both the `--deployment` names and their `--tag`s. */
-export declare function availableDeployments(config: WorkflowConfig, deployments?: WorkflowDeployment[]): string;
 /**
  * Project a deployment into the engine's {@link DeployTarget} — the shape the
  * deploy/diff verbs (`deployDefinitions`, `computeDiffEntries`, `diffEntry`)

package/dist/lib/select-deployment.js

@@ -66,7 +66,7 @@ async function chooseDeploymentName(deployments) {
         choices: deployments.map(({ name, tag }) => ({ name, value: name, description: `tag: ${tag}` })),
     });
 }
-export function availableDeployments(config, deployments = config.deployments) {
+function availableDeployments(config, deployments = config.deployments) {
     return `Available deployments: ${deployments.map(deploymentLabel).join(', ')}`;
 }
 export function deploymentToTarget(deployment) {

package/dist/lib/ui.d.ts

@@ -1,3 +1,4 @@
+import { styleText } from 'node:util';
 import type { ActivityStatus, WorkflowResource } from '@sanity/workflow-engine';
 /**
  * A bold `Title:` section heading. Mirrors the Sanity CLI's `sectionHeader`
@@ -8,12 +9,17 @@ export declare function sectionHeader(title: string): string;
  * A `  key:   value` detail row — a dim, padded key then the value. Mirrors
  * the Sanity CLI's `formatKeyValue` so it folds into the shared helper on
  * merge; pass `padTo` (the longest key's length) to align a block of rows.
+ *
+ * Pass `emphasis` (a {@link styleText} colour) to render the whole row — key
+ * and value together — bold in that colour instead of the dim-key default, so
+ * a standout row (a terminal instance status) pops from the neutral rows.
  */
-export declare function formatKeyValue({ key, value, indent, padTo, }: {
+export declare function formatKeyValue({ key, value, indent, padTo, emphasis, }: {
     key: string;
     value: string;
     indent?: number;
     padTo?: number;
+    emphasis?: Parameters<typeof styleText>[0];
 }): string;
 /**
  * A borderless column table as printable lines: cyan header row, every
@@ -37,9 +43,10 @@ export declare function clipToLimit<T>(rows: T[], limit: number): {
  * rows, render them through {@link formatTable}, print every line, and print
  * the clip note (when present) beneath the table.
  */
-export declare function logClippedTable<T>({ rows, limit, headers, toCells, log, }: {
+export declare function logClippedTable<T>({ rows, limit, moreAvailable, headers, toCells, log, }: {
     rows: T[];
     limit: number;
+    moreAvailable?: boolean;
     headers: string[];
     toCells: (row: T) => string[];
     log: (line: string) => void;

package/dist/lib/ui.js

@@ -6,9 +6,13 @@ import logSymbols from 'log-symbols';
 export function sectionHeader(title) {
     return styleText('bold', `${title}:`);
 }
-export function formatKeyValue({ key, value, indent = 2, padTo = 0, }) {
+export function formatKeyValue({ key, value, indent = 2, padTo = 0, emphasis, }) {
     const paddedKey = `${key}:`.padEnd(padTo > 0 ? padTo + 1 : key.length + 1);
-    return `${' '.repeat(indent)}${styleText('dim', paddedKey)} ${value}`;
+    const pad = ' '.repeat(indent);
+    if (emphasis) {
+        return `${pad}${styleText('bold', styleText(emphasis, `${paddedKey} ${value}`))}`;
+    }
+    return `${pad}${styleText('dim', paddedKey)} ${value}`;
 }
 export function formatTable(headers, rows) {
     const width = (cell) => stripVTControlCharacters(cell).length;
@@ -31,13 +35,14 @@ export function clipToLimit(rows, limit) {
         note: styleText('dim', `showing the first ${limit} — raise --limit to see more`),
     };
 }
-export function logClippedTable({ rows, limit, headers, toCells, log, }) {
+export function logClippedTable({ rows, limit, moreAvailable, headers, toCells, log, }) {
     const { rows: clipped, note } = clipToLimit(rows, limit);
     for (const line of formatTable(headers, clipped.map(toCells))) {
         log(line);
     }
-    if (note) {
-        log(note);
+    if (note || moreAvailable) {
+        log(note ??
+            styleText('dim', `searched the first ${limit} candidates — raise --limit to see more`));
     }
 }
 export function groupBanner({ label, index, total, }) {