Cursor rule

1---
2description: 'OCLIF command development patterns and CLI best practices'
3globs: ['**/commands/**/*.ts', '**/base-command.ts']
4alwaysApply: false
5---
6 
7# OCLIF Command Standards
8 
9## Command Structure
10 
11### Standard Command Pattern
12```typescript
13// ✅ GOOD - Standard command structure
14import { Command } from '@contentstack/cli-command';
15import { cliux, flags, FlagInput, handleAndLogError } from '@contentstack/cli-utilities';
16 
17export default class ConfigSetCommand extends Command {
18  static description = 'Set CLI configuration values';
19  
20  static flags: FlagInput = {
21    region: flags.string({
22      char: 'r',
23      description: 'Set region (us/eu)',
24    }),
25    alias: flags.string({
26      char: 'a',
27      description: 'Configuration alias',
28    }),
29  };
30  
31  static examples = [
32    'csdx config:set --region eu',
33    'csdx config:set --region us --alias default',
34  ];
35  
36  async run(): Promise<void> {
37    try {
38      const { flags: configFlags } = await this.parse(ConfigSetCommand);
39      // Command logic here
40    } catch (error) {
41      handleAndLogError(error, { module: 'config-set' });
42    }
43  }
44}
45```
46 
47## Base Classes
48 
49### Command Base Class
50```typescript
51// ✅ GOOD - Extend Command from @contentstack/cli-command
52import { Command } from '@contentstack/cli-command';
53 
54export default class MyCommand extends Command {
55  async run(): Promise<void> {
56    // Command implementation
57  }
58}
59```
60 
61### Custom Base Classes
62```typescript
63// ✅ GOOD - Create custom base classes for shared functionality
64export abstract class BaseCommand<T extends typeof Command> extends Command {
65  protected contextDetails = {
66    command: this.id || 'unknown',
67  };
68 
69  async init(): Promise<void> {
70    await super.init();
71    log.debug('Command initialized', this.contextDetails);
72  }
73}
74```
75 
76## OCLIF Configuration
77 
78### Package.json Setup
79```json
80{
81  "oclif": {
82    "commands": "./lib/commands",
83    "bin": "csdx",
84    "topicSeparator": ":"
85  }
86}
87```
88 
89### Command Topics
90- All commands use `cm` topic: `cm:config:set`, `cm:auth:login`
91- Built commands live in `lib/commands` (compiled from `src/commands`)
92- Commands use nested directories: `src/commands/config/set.ts` → `cm:config:set`
93 
94### Command Naming
95- **Topic hierarchy**: `config/remove/proxy.ts` → `cm:config:remove:proxy`
96- **Descriptive names**: Use verb-noun pattern (`set`, `remove`, `show`)
97- **Grouping**: Related commands share parent topics
98 
99## Flag Management
100 
101### Flag Definition Patterns
102```typescript
103// ✅ GOOD - Define flags clearly
104static flags: FlagInput = {
105  'stack-api-key': flags.string({
106    char: 'k',
107    description: 'Stack API key',
108    required: false,
109  }),
110  region: flags.string({
111    char: 'r',
112    description: 'Set region',
113    options: ['us', 'eu'],
114  }),
115  verbose: flags.boolean({
116    char: 'v',
117    description: 'Show verbose output',
118    default: false,
119  }),
120};
121```
122 
123### Flag Parsing
124```typescript
125// ✅ GOOD - Parse and validate flags
126async run(): Promise<void> {
127  const { flags: parsedFlags } = await this.parse(MyCommand);
128  
129  // Validate flag combinations
130  if (!parsedFlags['stack-api-key'] && !parsedFlags.alias) {
131    this.error('Either --stack-api-key or --alias is required');
132  }
133  
134  // Use parsed flags
135  const region = parsedFlags.region || 'us';
136}
137```
138 
139## Error Handling
140 
141### Standard Error Pattern
142```typescript
143// ✅ GOOD - Use handleAndLogError from utilities
144try {
145  await this.executeCommand();
146} catch (error) {
147  handleAndLogError(error, { module: 'my-command' });
148}
149```
150 
151### User-Friendly Messages
152```typescript
153// ✅ GOOD - Clear user feedback
154import { cliux } from '@contentstack/cli-utilities';
155 
156// Success message
157cliux.success('Configuration updated successfully', { color: 'green' });
158 
159// Error message
160cliux.error('Invalid region specified', { color: 'red' });
161 
162// Info message
163cliux.print('Setting region to eu', { color: 'blue' });
164```
165 
166## Validation Patterns
167 
168### Early Validation
169```typescript
170// ✅ GOOD - Validate flags early
171async run(): Promise<void> {
172  const { flags } = await this.parse(MyCommand);
173  
174  // Validate required flags
175  if (!flags.region) {
176    this.error('--region is required');
177  }
178  
179  // Validate flag values
180  if (!['us', 'eu'].includes(flags.region)) {
181    this.error('Region must be "us" or "eu"');
182  }
183  
184  // Proceed with validated input
185}
186```
187 
188## Progress and Logging
189 
190### User Feedback
191```typescript
192// ✅ GOOD - Provide user feedback
193import { log, cliux } from '@contentstack/cli-utilities';
194 
195// Regular logging
196this.log('Starting configuration update...');
197 
198// Debug logging
199log.debug('Detailed operation information', { context: 'data' });
200 
201// Status messages
202cliux.print('Processing...', { color: 'blue' });
203```
204 
205### Progress Indication
206```typescript
207// ✅ GOOD - Show progress for long operations
208cliux.print('Processing items...', { color: 'blue' });
209let count = 0;
210for (const item of items) {
211  await this.processItem(item);
212  count++;
213  cliux.print(`Processed ${count}/${items.length} items`, { color: 'blue' });
214}
215```
216 
217## Command Delegation
218 
219### Service Layer Separation
220```typescript
221// ✅ GOOD - Commands orchestrate, services implement
222async run(): Promise<void> {
223  try {
224    const { flags } = await this.parse(MyCommand);
225    const config = this.buildConfig(flags);
226    const service = new ConfigService(config);
227    
228    await service.execute();
229    cliux.success('Operation completed successfully');
230  } catch (error) {
231    this.handleError(error);
232  }
233}
234```
235 
236## Testing Commands
237 
238### OCLIF Test Support
239```typescript
240// ✅ GOOD - Use @oclif/test for command testing
241import { test } from '@oclif/test';
242 
243describe('cm:config:set', () => {
244  test
245    .stdout()
246    .command(['cm:config:set', '--help'])
247    .it('shows help', ctx => {
248      expect(ctx.stdout).to.contain('Set CLI configuration');
249    });
250 
251  test
252    .stdout()
253    .command(['cm:config:set', '--region', 'eu'])
254    .it('sets region to eu', ctx => {
255      expect(ctx.stdout).to.contain('success');
256    });
257});
258```
259 
260## Log Integration
261 
262### Debug Logging
263```typescript
264// ✅ GOOD - Use structured debug logging
265import { log } from '@contentstack/cli-utilities';
266 
267log.debug('Command started', { 
268  command: this.id, 
269  flags: this.flags,
270  timestamp: new Date().toISOString(),
271});
272 
273log.debug('Processing complete', { 
274  itemsProcessed: count,
275  module: 'my-command',
276});
277```
278 
279### Error Context
280```typescript
281// ✅ GOOD - Include context in error handling
282try {
283  await operation();
284} catch (error) {
285  handleAndLogError(error, { 
286    module: 'config-set',
287    command: 'cm:config:set',
288    flags: { region: 'eu' },
289  });
290}
291```
292 
293## Multi-Topic Commands
294 
295### Nested Command Structure
296```typescript
297// File: src/commands/config/show.ts
298export default class ShowConfigCommand extends Command {
299  static description = 'Show current configuration';
300  static examples = ['csdx config:show'];
301  async run(): Promise<void> { }
302}
303 
304// File: src/commands/config/set.ts
305export default class SetConfigCommand extends Command {
306  static description = 'Set configuration values';
307  static examples = ['csdx config:set --region eu'];
308  async run(): Promise<void> { }
309}
310 
311// Generated commands:
312// - cm:config:show
313// - cm:config:set
314```
315 
316## Best Practices
317 
318### Command Organization
319```typescript
320// ✅ GOOD - Well-organized command
321export default class MyCommand extends Command {
322  static description = 'Clear, concise description';
323  
324  static flags: FlagInput = {
325    // Define all flags
326  };
327  
328  static examples = [
329    'csdx my:command',
330    'csdx my:command --flag value',
331  ];
332  
333  async run(): Promise<void> {
334    try {
335      const { flags } = await this.parse(MyCommand);
336      await this.execute(flags);
337    } catch (error) {
338      handleAndLogError(error, { module: 'my-command' });
339    }
340  }
341  
342  private async execute(flags: Flags<typeof MyCommand>): Promise<void> {
343    // Implementation
344  }
345}
346```
347 
348### Clear Help Text
349- Write description as action-oriented statement
350- Provide multiple examples for common use cases
351- Document each flag with clear description
352- Show output format or examples of results
353