ably-cli AGENTS.md

AGENTS.md - Ably CLI

Mandatory Workflow

Run these IN ORDER for EVERY change:

pnpm prepare        # 1. Build + update manifest
pnpm generate-doc  # 2. Regenerate docs (gitignored)
pnpm exec eslint .  # 3. Lint (MUST be 0 errors)
pnpm test:unit      # 4. Test (at minimum)
pnpm test:tty       # 5. TTY tests (local only, skip in CI)
                    # 6. Update docs if needed

If you skip these steps, the work is NOT complete.

Project Context

This is the Ably CLI npm package (@ably/cli), built with the oclif framework.

.
├── src/
│   ├── commands/      # CLI commands (oclif)
│   ├── services/      # Business logic
│   ├── utils/         # Utilities
│   └── base-command.ts
├── test/
│   ├── unit/          # Fast, mocked
│   ├── integration/   # Multi-component, mocked external services
│   ├── e2e/           # Full scenarios against real Ably
│   └── helpers/       # runCommand(), MockConfigManager, etc.
├── docs/              # Project docs (Testing.md, Project-Structure.md, etc.)
└── package.json       # Scripts defined here

Common Pitfalls - DO NOT DO THESE

1. Skip tests - Only skip with documented valid reason
2. Use _ prefix for unused variables - Remove the code instead
3. Leave debug code - Remove ALL console.log, DEBUG_TEST, test-*.mjs
4. Use // eslint-disable - Fix the root cause
5. Remove tests without asking - Always get permission first
6. NODE_ENV - To check if the CLI is in test mode, use the isTestMode() helper function.
7. process.exit - When creating a command, use this.exit() for consistent test mode handling.
8. console.log / console.error - In commands, always use this.log() (stdout) for data/results and the logging helpers (this.logProgress(), this.logSuccessMessage(), this.logListening(), this.logHolding(), this.logWarning()) for status messages. console.* bypasses oclif and can't be captured by tests.
9. Use Args.string() for primary entity identifiers - If the value is "what is being acted on" (name, ID, channel), represent it as a positional Args.string(), not a Flags.string(). Primary entity identifiers should always use camelCase.