feat: implement unknown flag detection and enhance search result messaging

src/commands/search.ts

@@ -9,6 +9,46 @@ import { parseBetween, buildDateFilter } from '../date-filter.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',
+]);
+
+/**
+ * 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.
@@ -71,6 +111,9 @@ const toBigIntSafe = (value: unknown): bigint => {
   }
 };
 
+/** Default page size the Camunda REST API uses when no explicit limit is set */
+export 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;
 
@@ -111,14 +154,41 @@ 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.
+ */
+export function logNoResults(logger: Logger, resourceName: string, hasFilters: boolean, unknownFlags?: string[]): void {
+  if (unknownFlags && unknownFlags.length > 0) {
+    const flagList = unknownFlags.map(f => `--${f}`).join(', ');
+    logger.info(`🕳️ No ${resourceName} found matching the criteria (ignored unknown flag(s): ${flagList})`);
+  } else {
+    logger.info(`🕳️ No ${resourceName} found matching the criteria`);
+  }
+  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.
+ */
+export 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
  */
@@ -132,6 +202,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);
@@ -218,9 +289,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;
@@ -243,6 +314,7 @@ export async function searchProcessInstances(options: {
   iProcessDefinitionId?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
   between?: string;
   dateField?: string;
 }): Promise<SearchResult | undefined> {
@@ -336,9 +408,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;
@@ -361,6 +433,7 @@ export async function searchUserTasks(options: {
   iAssignee?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
   between?: string;
   dateField?: string;
 }): Promise<SearchResult | undefined> {
@@ -455,9 +528,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;
@@ -482,6 +555,7 @@ export async function searchIncidents(options: {
   iProcessDefinitionId?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
   between?: string;
 }): Promise<SearchResult | undefined> {
   const logger = getLogger();
@@ -587,9 +661,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;
@@ -611,6 +685,7 @@ export async function searchJobs(options: {
   iType?: string;
   sortBy?: string;
   sortOrder?: SortOrder;
+  _unknownFlags?: string[];
   between?: string;
   dateField?: string;
 }): Promise<SearchResult | undefined> {
@@ -698,9 +773,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;
@@ -725,6 +800,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);
@@ -833,13 +909,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

@@ -4,7 +4,9 @@
  * Main entry point
  */
 
+import { realpathSync } from 'node:fs';
 import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
 import { getLogger, type SortOrder } from './logger.ts';
 import { c8ctl } from './runtime.ts';
 import { loadSessionState } from './config.ts';
@@ -28,6 +30,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';
@@ -144,6 +147,17 @@ export 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
  */
@@ -666,18 +680,21 @@ 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: resolveProcessDefinitionId(values),
         name: values.name as string | undefined,
-        version: (values.version_num && typeof values.version_num === 'string') ? parseInt(values.version_num) : undefined,
+        version: (values.version && typeof values.version === 'string') ? parseInt(values.version) : 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;
     }
@@ -693,6 +710,7 @@ async function main() {
         iProcessDefinitionId: values.iid as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
         between: values.between as string | undefined,
         dateField: values.dateField as string | undefined,
       });
@@ -710,6 +728,7 @@ async function main() {
         iAssignee: values.iassignee as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
         between: values.between as string | undefined,
         dateField: values.dateField as string | undefined,
       });
@@ -729,6 +748,7 @@ async function main() {
         iProcessDefinitionId: values.iid as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
         between: values.between as string | undefined,
       });
       return;
@@ -744,6 +764,7 @@ async function main() {
         iType: values.itype as string | undefined,
         sortBy: values.sortBy as string | undefined,
         sortOrder,
+        _unknownFlags: unknownFlags,
         between: values.between as string | undefined,
         dateField: values.dateField as string | undefined,
       });
@@ -763,6 +784,7 @@ async function main() {
         sortBy: values.sortBy as string | undefined,
         sortOrder,
         limit,
+        _unknownFlags: unknownFlags,
       });
       return;
     }
@@ -790,9 +812,12 @@ async function main() {
 }
 
 // Run the CLI only when invoked directly (not when imported)
-if (process.argv[1] === new URL(import.meta.url).pathname) {
-  main().catch((error) => {
-    console.error('Unexpected error:', error);
-    process.exit(1);
-  });
-}
+// Use realpathSync to resolve symlinks (e.g. when installed globally via npm link)
+try {
+  if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+      console.error('Unexpected error:', error);
+      process.exit(1);
+    });
+  }
+} catch { /* not invoked directly */ }