|
| 1 | +# AGENTS.md - Agent Coding Guidelines |
| 2 | + |
| 3 | +This document provides guidelines for agents operating in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +- **Name**: mmx-cli |
| 8 | +- **Type**: Node.js CLI tool (ESM, Bun-native) |
| 9 | +- **Engine**: Node.js 18+ |
| 10 | +- **Language**: TypeScript (strict mode) |
| 11 | + |
| 12 | +## Commands |
| 13 | + |
| 14 | +### Build, Lint, Test |
| 15 | + |
| 16 | +```bash |
| 17 | +# Build for production |
| 18 | +bun run build |
| 19 | + |
| 20 | +# Build for development (faster, non-minified) |
| 21 | +bun run build:dev |
| 22 | + |
| 23 | +# Run development (direct execution) |
| 24 | +bun run dev |
| 25 | + |
| 26 | +# Lint (ESLint + TypeScript-eslint) |
| 27 | +bun run lint |
| 28 | + |
| 29 | +# Type check (TypeScript) |
| 30 | +bun run typecheck |
| 31 | + |
| 32 | +# Run all tests |
| 33 | +bun test |
| 34 | + |
| 35 | +# Run tests in watch mode |
| 36 | +bun test --watch |
| 37 | + |
| 38 | +# Run a single test file |
| 39 | +bun test test/commands/auth/login.test.ts |
| 40 | + |
| 41 | +# Run tests matching a pattern |
| 42 | +bun test --grep "auth login" |
| 43 | +``` |
| 44 | + |
| 45 | +### Publishing |
| 46 | + |
| 47 | +```bash |
| 48 | +npm publish |
| 49 | +``` |
| 50 | + |
| 51 | +## Code Style |
| 52 | + |
| 53 | +### TypeScript |
| 54 | + |
| 55 | +- **Strict mode**: Always enabled (`strict: true` in tsconfig.json) |
| 56 | +- **No explicit `any`**: Avoid `any`; use `unknown` if type is truly unknown |
| 57 | +- **Unused variables**: Prefix with `_` if intentionally unused (e.g., `_unused: string`) |
| 58 | + |
| 59 | +### Imports |
| 60 | + |
| 61 | +- Use ES modules (`import ... from '...'`) |
| 62 | +- Order: external → internal → relative |
| 63 | +- Group by: imports → types → constants → logic |
| 64 | + |
| 65 | +```typescript |
| 66 | +// 1. External imports |
| 67 | +import { foo } from 'external-package'; |
| 68 | +import type { SomeType } from 'external-package'; |
| 69 | + |
| 70 | +// 2. Internal absolute imports |
| 71 | +import { registry } from './registry'; |
| 72 | +import type { Config } from './config/schema'; |
| 73 | + |
| 74 | +// 3. Relative imports (if any) |
| 75 | +``` |
| 76 | + |
| 77 | +### File Naming |
| 78 | + |
| 79 | +- **Files**: `kebab-case.ts` |
| 80 | +- **Directories**: `kebab-case/` |
| 81 | +- **Test files**: `*.test.ts` (co-located with source or in `test/`) |
| 82 | + |
| 83 | +### Function/Variable Naming |
| 84 | + |
| 85 | +- **Functions**: `camelCase` (e.g., `loadConfig`, `checkForUpdate`) |
| 86 | +- **Constants**: `SCREAMING_SNAKE_CASE` (e.g., `REGIONS`, `CLI_VERSION`) |
| 87 | +- **Interfaces/Types**: `PascalCase` (e.g., `Command`, `Config`, `GlobalFlags`) |
| 88 | +- **Enums**: `PascalCase` for both enum and members |
| 89 | + |
| 90 | +### Error Handling |
| 91 | + |
| 92 | +- Use custom error hierarchy: `src/errors/` (base.ts, api.ts, codes.ts, handler.ts) |
| 93 | +- Always catch and handle errors appropriately |
| 94 | +- Use `handleError` for CLI exit scenarios |
| 95 | + |
| 96 | +```typescript |
| 97 | +// Preferred pattern |
| 98 | +async function myCommand(config: Config, flags: GlobalFlags): Promise<void> { |
| 99 | + try { |
| 100 | + await doSomething(); |
| 101 | + } catch (error) { |
| 102 | + if (error instanceof ApiError) { |
| 103 | + // Handle API error |
| 104 | + } |
| 105 | + throw error; |
| 106 | + } |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +### Async/Await |
| 111 | + |
| 112 | +- Always `await` promises; never use `.then()` chain |
| 113 | +- Handle async errors with try/catch in async functions |
| 114 | + |
| 115 | +### Configuration |
| 116 | + |
| 117 | +- Use Zod for config schema validation (see `src/config/schema.ts`) |
| 118 | +- Define options with `OptionDef` interface (see `src/command.ts`) |
| 119 | + |
| 120 | +### Output |
| 121 | + |
| 122 | +- Use provided output utilities: `src/output/` (text.ts, json.ts, progress.ts, etc.) |
| 123 | +- Respect `--output` flag for format selection |
| 124 | +- Use `--quiet` to suppress non-essential output |
| 125 | + |
| 126 | +### Testing |
| 127 | + |
| 128 | +- Use Bun's built-in test runner (`bun test`) |
| 129 | +- Co-locate tests in `test/` directory |
| 130 | +- Use descriptive test names: `it('should do X when Y')` |
| 131 | +- Mock external dependencies as needed |
| 132 | + |
| 133 | +```typescript |
| 134 | +import { describe, it, expect, mock } from 'bun:test'; |
| 135 | + |
| 136 | +describe('auth/login', () => { |
| 137 | + it('should login successfully', () => { |
| 138 | + expect(true).toBe(true); |
| 139 | + }); |
| 140 | +}); |
| 141 | +``` |
| 142 | + |
| 143 | +### Git Conventions |
| 144 | + |
| 145 | +- Commit message format: `<type>: <description>` |
| 146 | +- Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore` |
| 147 | +- Keep commits atomic and focused |
| 148 | + |
| 149 | +## Project Structure |
| 150 | + |
| 151 | +``` |
| 152 | +src/ |
| 153 | +├── auth/ # Authentication (login, oauth, refresh, credentials) |
| 154 | +├── client/ # HTTP client, endpoints, streaming |
| 155 | +├── command.ts # Command interface and definitions |
| 156 | +├── commands/ # Command implementations (auth/, config/, video/, etc.) |
| 157 | +├── config/ # Config loading, schema, region detection |
| 158 | +├── errors/ # Error handling (base, api, codes, handler) |
| 159 | +├── output/ # Output formatters (text, json, progress, audio, etc.) |
| 160 | +├── polling/ # Long-polling utilities |
| 161 | +├── types/ # Type definitions (api, commands, flags) |
| 162 | +├── utils/ # Utilities (fs, token, env, prompt, schema) |
| 163 | +├── update/ # Self-update checker |
| 164 | +├── args.ts # Argument parsing |
| 165 | +├── main.ts # CLI entry point |
| 166 | +└── registry.ts # Command registry |
| 167 | +``` |
| 168 | + |
| 169 | +## Key Patterns |
| 170 | + |
| 171 | +### Defining a Command |
| 172 | + |
| 173 | +```typescript |
| 174 | +import type { CommandSpec } from './command'; |
| 175 | + |
| 176 | +export const myCommand: CommandSpec = { |
| 177 | + name: 'my-command', |
| 178 | + description: 'Does something useful', |
| 179 | + options: [ |
| 180 | + { flag: '--option <value>', description: 'An option', type: 'string' }, |
| 181 | + ], |
| 182 | + run: async (config, flags) => { |
| 183 | + // Implementation |
| 184 | + }, |
| 185 | +}; |
| 186 | +``` |
| 187 | + |
| 188 | +### API Calls |
| 189 | + |
| 190 | +```typescript |
| 191 | +import { http } from '../client/http'; |
| 192 | + |
| 193 | +const response = await http.request('/endpoint', { |
| 194 | + method: 'POST', |
| 195 | + body: JSON.stringify(payload), |
| 196 | + headers: { 'Content-Type': 'application/json' }, |
| 197 | +}); |
| 198 | +``` |
| 199 | + |
| 200 | +## Common Tasks |
| 201 | + |
| 202 | +- **Add a new command**: Create `src/commands/<category>/<command>.ts`, register in `src/registry.ts` |
| 203 | +- **Add config option**: Update `src/config/schema.ts` and `src/command.ts` |
| 204 | +- **Add API endpoint**: Update `src/client/endpoints.ts` |
| 205 | +- **Add error code**: Update `src/errors/codes.ts` |
0 commit comments