Skip to main content
All usage examples from the package, aggregated for quick reference.

​
ExternalTaskProvider

Interface that provider adapters implement to expose their external task system to the reconciliation engine. Provider-specific parsing lives in the adapter — core never sees native formats. Consumers implement this interface to integrate their issue tracker with CLEO. View in API reference 
class LinearAdapter implements ExternalTaskProvider {
  async getExternalTasks(projectDir: string): Promise<ExternalTask[]> {
    const issues = await linearClient.issues({ projectId: '...' });
    return issues.map(issue => ({
      externalId: issue.id,
      title: issue.title,
      status: mapLinearStatus(issue.state),
      description: issue.description,
      priority: mapLinearPriority(issue.priority),
      labels: issue.labels.map(l => l.name),
      url: issue.url,
      providerMeta: { linearId: issue.identifier },
    }));
  }
}

​
normalizeError()

Normalize any thrown value into a standardized error object. Handles: - Error instances (preserves stack trace info) - Strings (wraps in Error) - Objects with message property - null/undefined (provides fallback) View in API reference 
try {
  await riskyOperation();
} catch (err) {
  const error = normalizeError(err, 'Operation failed');
  console.error(error.message);
}

​
getErrorMessage()

Extract a human-readable message from any error value. Safe to use on unknown thrown values without type guards. View in API reference 
const message = getErrorMessage(err, 'Unknown error');

​
formatError()

Format error details for logging or display. Includes stack trace for Error instances when includeStack is true. View in API reference 
console.error(formatError(err, 'Database connection'));
// Output: [Database connection] Connection refused

​
isErrorType()

Check if an error represents a specific error type by code or name. Useful for conditional error handling based on error types. View in API reference 
if (isErrorType(err, 'E_NOT_FOUND')) {
  // Handle not found specifically
}

​
createErrorResult()

Create a standardized error result object. Common pattern for operations that return success: boolean, error?: string View in API reference 
return createErrorResult(err);
// Returns: { success: false, error: "Something went wrong" }

​
createSuccessResult()

Create a standardized success result object. View in API reference 
return createSuccessResult();
// Returns: { success: true }

​
isErrorResult()

Type guard for error results. View in API reference 
const result = await someOperation();
if (isErrorResult(result)) {
  console.error(result.error);
}

​
isLafsSuccess()

Type guard for success responses. View in API reference 
const result: LafsEnvelope<Task[]> = await fetchTasks();
if (isLafsSuccess(result)) {
  console.log(result.data); // Task[]
}

​
isLafsError()

Type guard for error responses. View in API reference 
const result: LafsEnvelope<Task[]> = await fetchTasks();
if (isLafsError(result)) {
  console.error(result.error.message);
}

​
isGatewayEnvelope()

Type guard for gateway responses (has _meta). View in API reference 
const response: CleoResponse<Task> = await handleRequest();
if (isGatewayEnvelope(response)) {
  console.log(response._meta.gateway);
}