feat: implement unknown flag detection and enhance search result messaging

src/commands/search.ts

@@ -8,6 +8,46 @@ import { resolveTenantId } from '../config.ts';
 
 export type SearchResult = { items: Array<Record<string, unknown>>; total?: number };
 
+/**
+ * Flags that are valid globally (not specific to any search resource).
+ */
+export const GLOBAL_FLAGS = new Set([
+  'profile', 'sortBy', 'asc', 'desc', 'help', 'version', 'limit',
+]);
+
+/**
+ * Valid search filter flags per resource (values keys that are consumed by the search handler).
+ * This map is used to detect when a user passes a flag that looks valid but is not recognized
+ * for the specific resource, causing silent filter drops.
+ */
+export const SEARCH_RESOURCE_FLAGS: Record<string, Set<string>> = {
+  'process-definition': new Set(['bpmnProcessId', 'id', 'processDefinitionId', 'name', 'key', 'iid', 'iname']),
+  'process-instance': new Set(['bpmnProcessId', 'id', 'processDefinitionId', 'processDefinitionKey', 'state', 'key', 'parentProcessInstanceKey', 'iid']),
+  'user-task': new Set(['state', 'assignee', 'processInstanceKey', 'processDefinitionKey', 'elementId', 'iassignee']),
+  'incident': new Set(['state', 'processInstanceKey', 'processDefinitionKey', 'bpmnProcessId', 'id', 'processDefinitionId', 'errorType', 'errorMessage', 'ierrorMessage', 'iid']),
+  'jobs': new Set(['state', 'type', 'processInstanceKey', 'processDefinitionKey', 'itype']),
+  'variable': new Set(['name', 'value', 'processInstanceKey', 'scopeKey', 'fullValue', 'iname', 'ivalue', 'limit']),
+};
+
+/**
+ * Detect flags the user set that are not recognized for the given search resource.
+ * Returns the list of unknown flag names (without the --prefix).
+ */
+export function detectUnknownSearchFlags(values: Record<string, unknown>, normalizedResource: string): string[] {
+  const validFlags = SEARCH_RESOURCE_FLAGS[normalizedResource]
+    || SEARCH_RESOURCE_FLAGS[normalizedResource.replace(/s$/, '')];
+  if (!validFlags) return [];
+
+  const unknown: string[] = [];
+  for (const [key, val] of Object.entries(values)) {
+    if (val === undefined || val === false) continue; // not set by the user
+    if (GLOBAL_FLAGS.has(key)) continue;
+    if (validFlags.has(key)) continue;
+    unknown.push(key);
+  }
+  return unknown;
+}
+
 /**
  * Detect wildcard characters (* or ?) in a string value and return
  * a $like filter object for the API. Returns the plain string for exact match.
@@ -70,6 +110,9 @@ const toBigIntSafe = (value: unknown): bigint => {
   }
 };
 
+/** Default page size the Camunda REST API uses when no explicit limit is set */
+const API_DEFAULT_PAGE_SIZE = 100;
+
 /** Max page size for case-insensitive search (client-side filtering needs broader result set) */
 const CI_PAGE_SIZE = 1000;
 
@@ -110,14 +153,38 @@ function formatCriterion(fieldLabel: string, value: string | number | boolean, i
  */
 function logSearchCriteria(logger: Logger, resourceName: string, criteria: string[]): void {
   if (criteria.length === 0) {
-    logger.info(`Searching ${resourceName}`);
+    logger.info(`Searching ${resourceName} (no filters)`);
   } else if (criteria.length === 1) {
     logger.info(`Searching ${resourceName} where ${criteria[0]}`);
   } else {
     logger.info(`Searching ${resourceName} where ${criteria.join(' AND ')}`);
   }
 }
 
+/**
+ * Log a "no results" message with 🕳️ emoji and contextual hint.
+ */
+function logNoResults(logger: Logger, resourceName: string, hasFilters: boolean, unknownFlags?: string[]): void {
+  logger.info(`🕳️ No ${resourceName} found matching the criteria`);
+  if (unknownFlags && unknownFlags.length > 0) {
+    logger.warn(`Possibly unused flag(s): ${unknownFlags.map(f => `--${f}`).join(', ')}. Run "c8ctl help search" for valid options.`);
+  } else if (!hasFilters) {
+    logger.info('No filters were applied. Use "c8ctl help search" to see available filter flags.');
+  }
+}
+
+/**
+ * Log the result count with a truncation warning when the count matches the API default page size.
+ */
+function logResultCount(logger: Logger, count: number, resourceName: string, hasFilters: boolean): void {
+  logger.info(`Found ${count} ${resourceName}`);
+  if (count === API_DEFAULT_PAGE_SIZE && !hasFilters) {
+    logger.warn(`Showing first ${API_DEFAULT_PAGE_SIZE} results (API default page size). More results may exist — add filters to narrow down.`);
+  } else if (count === API_DEFAULT_PAGE_SIZE) {
+    logger.warn(`Result count equals the API default page size (${API_DEFAULT_PAGE_SIZE}). There may be more results.`);
+  }
+}
+
 /**
  * Search process definitions
  */
@@ -131,6 +198,7 @@ export async function searchProcessDefinitions(options: {
   iName?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
   const client = createClient(options.profile);
@@ -217,9 +285,9 @@ export async function searchProcessDefinitions(options: {
       }));
       tableData = sortTableData(tableData, options.sortBy, logger, options.sortOrder);
       logger.table(tableData);
-      logger.info(`Found ${result.items.length} process definition(s)`);
+      logResultCount(logger, result.items.length, 'process definition(s)', criteria.length > 0);
     } else {
-      logger.info('No process definitions found matching the criteria');
+      logNoResults(logger, 'process definitions', criteria.length > 0, options._unknownFlags);
     }
 
     return result as SearchResult;
@@ -242,6 +310,7 @@ export async function searchProcessInstances(options: {
   iProcessDefinitionId?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
   const client = createClient(options.profile);
@@ -318,9 +387,9 @@ export async function searchProcessInstances(options: {
       }));
       tableData = sortTableData(tableData, options.sortBy, logger, options.sortOrder);
       logger.table(tableData);
-      logger.info(`Found ${result.items.length} process instance(s)`);
+      logResultCount(logger, result.items.length, 'process instance(s)', criteria.length > 0);
     } else {
-      logger.info('No process instances found matching the criteria');
+      logNoResults(logger, 'process instances', criteria.length > 0, options._unknownFlags);
     }
 
     return result as SearchResult;
@@ -343,6 +412,7 @@ export async function searchUserTasks(options: {
   iAssignee?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
   const client = createClient(options.profile);
@@ -420,9 +490,9 @@ export async function searchUserTasks(options: {
       }));
       tableData = sortTableData(tableData, options.sortBy, logger, options.sortOrder);
       logger.table(tableData);
-      logger.info(`Found ${result.items.length} user task(s)`);
+      logResultCount(logger, result.items.length, 'user task(s)', criteria.length > 0);
     } else {
-      logger.info('No user tasks found matching the criteria');
+      logNoResults(logger, 'user tasks', criteria.length > 0, options._unknownFlags);
     }
 
     return result as SearchResult;
@@ -447,6 +517,7 @@ export async function searchIncidents(options: {
   iProcessDefinitionId?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
   const client = createClient(options.profile);
@@ -538,9 +609,9 @@ export async function searchIncidents(options: {
       }));
       tableData = sortTableData(tableData, options.sortBy, logger, options.sortOrder);
       logger.table(tableData);
-      logger.info(`Found ${result.items.length} incident(s)`);
+      logResultCount(logger, result.items.length, 'incident(s)', criteria.length > 0);
     } else {
-      logger.info('No incidents found matching the criteria');
+      logNoResults(logger, 'incidents', criteria.length > 0, options._unknownFlags);
     }
 
     return result as SearchResult;
@@ -562,6 +633,7 @@ export async function searchJobs(options: {
   iType?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
   const client = createClient(options.profile);
@@ -632,9 +704,9 @@ export async function searchJobs(options: {
       }));
       tableData = sortTableData(tableData, options.sortBy, logger, options.sortOrder);
       logger.table(tableData);
-      logger.info(`Found ${result.items.length} job(s)`);
+      logResultCount(logger, result.items.length, 'job(s)', criteria.length > 0);
     } else {
-      logger.info('No jobs found matching the criteria');
+      logNoResults(logger, 'jobs', criteria.length > 0, options._unknownFlags);
     }
 
     return result as SearchResult;
@@ -659,6 +731,7 @@ export async function searchVariables(options: {
   sortBy?: string;
   sortOrder?: SortOrder;
   limit?: number;
+  _unknownFlags?: string[];
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
   const client = createClient(options.profile);
@@ -767,13 +840,13 @@ export async function searchVariables(options: {
       });
       tableData = sortTableData(tableData, options.sortBy, logger, options.sortOrder);
       logger.table(tableData);
-      logger.info(`Found ${result.items.length} variable(s)`);
+      logResultCount(logger, result.items.length, 'variable(s)', criteria.length > 0);
 
       if (!options.fullValue && result.items.some((v: any) => v.isTruncated)) {
         logger.info('Some values are truncated. Use --fullValue to see full values.');
       }
     } else {
-      logger.info('No variables found matching the criteria');
+      logNoResults(logger, 'variables', criteria.length > 0, options._unknownFlags);
     }
 
     return result as SearchResult;

src/index.ts

@@ -28,6 +28,7 @@ import {
   searchIncidents,
   searchJobs,
   searchVariables,
+  detectUnknownSearchFlags,
 } from './commands/search.ts';
 import { listUserTasks, completeUserTask } from './commands/user-tasks.ts';
 import { listIncidents, getIncident, resolveIncident } from './commands/incidents.ts';
@@ -142,6 +143,17 @@ function resolveProcessDefinitionId(values: any): string | undefined {
   return (values.id || values.processDefinitionId || values.bpmnProcessId) as string | undefined;
 }
 
+/**
+ * Warn about unrecognized flags for a search resource.
+ */
+function warnUnknownSearchFlags(logger: ReturnType<typeof getLogger>, unknownFlags: string[], resource: string): void {
+  if (unknownFlags.length === 0) return;
+  const flagList = unknownFlags.map(f => `--${f}`).join(', ');
+  logger.warn(
+    `Flag(s) ${flagList} not recognized for 'search ${resource}'. They will be ignored. Run "c8ctl help search" for valid options.`,
+  );
+}
+
 /**
  * Main CLI handler
  */
@@ -657,33 +669,37 @@ async function main() {
   // Handle search commands
   if (verb === 'search') {
     const normalizedSearchResource = normalizeResource(resource);
+    const unknownFlags = detectUnknownSearchFlags(values as Record<string, unknown>, normalizedSearchResource);
+    warnUnknownSearchFlags(logger, unknownFlags, resource);
 
     if (normalizedSearchResource === 'process-definition' || normalizedSearchResource === 'process-definitions') {
       await searchProcessDefinitions({
         profile: values.profile as string | undefined,
-        processDefinitionId: values.bpmnProcessId as string | undefined,
+        processDefinitionId: resolveProcessDefinitionId(values),
         name: values.name as string | undefined,
         version: (values.version_num && typeof values.version_num === 'string') ? parseInt(values.version_num) : undefined,
         key: values.key as string | undefined,
         iProcessDefinitionId: values.iid as string | undefined,
         iName: values.iname as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
       });
       return;
     }
 
     if (normalizedSearchResource === 'process-instance' || normalizedSearchResource === 'process-instances') {
       await searchProcessInstances({
         profile: values.profile as string | undefined,
-        processDefinitionId: values.bpmnProcessId as string | undefined,
+        processDefinitionId: resolveProcessDefinitionId(values),
         processDefinitionKey: values.processDefinitionKey as string | undefined,
         state: values.state as string | undefined,
         key: values.key as string | undefined,
         parentProcessInstanceKey: values.parentProcessInstanceKey as string | undefined,
         iProcessDefinitionId: values.iid as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
       });
       return;
     }
@@ -699,6 +715,7 @@ async function main() {
         iAssignee: values.iassignee as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
       });
       return;
     }
@@ -709,13 +726,14 @@ async function main() {
         state: values.state as string | undefined,
         processInstanceKey: values.processInstanceKey as string | undefined,
         processDefinitionKey: values.processDefinitionKey as string | undefined,
-        processDefinitionId: values.bpmnProcessId as string | undefined,
+        processDefinitionId: resolveProcessDefinitionId(values),
         errorType: values.errorType as string | undefined,
         errorMessage: values.errorMessage as string | undefined,
         iErrorMessage: values.ierrorMessage as string | undefined,
         iProcessDefinitionId: values.iid as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
       });
       return;
     }
@@ -730,6 +748,7 @@ async function main() {
         iType: values.itype as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
       });
       return;
     }
@@ -747,6 +766,7 @@ async function main() {
         sortBy: values.sortBy as string | undefined,
         sortOrder,
         limit,
+        _unknownFlags: unknownFlags,
       });
       return;
     }