Arch Cli

Import Rules

Patterns

Command handler — resolve → validate → call → output → catch

// Good
export async function startCommand(task: string, options: RawStartOptions) {
  try {
    const agentService = container.resolve<AgentService>(TOKENS.AgentService)
    const config = container.resolve<Config>(TOKENS.Config)
    const input = parseStartSession({ task, ...options })          // validate first
    const { sessionId, response } = await agentService.start(...)
    stdout.print(`Session created: ${sessionId}`)
    printResponse(response, input, config.display, { sessionId })
  } catch (error) {
    if (error instanceof ValidationError) { stderr.print(`Invalid arguments: ${error.message}`) }
    else if (error instanceof RateLimitError) { stderr.print(`...`) }
    else { stderr.print('Failed to start session', error as Error) }
    process.exit(1)
  }
}

// Bad — raw options used directly without validation, wrong output method
export async function startCommand(task: string, options: RawStartOptions) {
  const service = new AgentService()                    // direct instantiation
  await service.start(task, options.model)              // unvalidated options
  console.log('done')                                   // console.log
}

--output-only flag — implies all three --silent-* flags

// Good
const silentThoughts = opts.outputOnly || opts.silentThoughts

// Bad — treats outputOnly as a fourth independent flag
if (opts.outputOnly) { /* only hides one thing */ }

commander v12 option naming — kebab-case in .option() → camelCase in handler

// Good
.option('--allowed-tools <tools...>', '...')   // handler receives: options.allowedTools
.option('--output-only', '...')                // handler receives: options.outputOnly

// Bad
.option('--allowedTools <tools...>', '...')    // commander won't camelCase this correctly

Prohibitions

• Never use console.log / console.error — always stdout.print() (normal output) / stderr.print() (errors), both from @src/utils/output
• Never import from repositories/ or infrastructures/ — route through a service
• Never skip parseXxx() — always validate raw options.* before passing to services
• Never call setupContainer() inside command handlers — it belongs only in index.ts
• Never instantiate services directly — use container.resolve<T>(TOKENS.Xxx)