|
| 1 | +# Developing Flarum CLI |
| 2 | + |
| 3 | +This guide covers how to set up and work with the Flarum CLI codebase locally. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Node.js >= 18.0.0 |
| 8 | +- Yarn package manager |
| 9 | + |
| 10 | +## Initial Setup |
| 11 | + |
| 12 | +1. **Clone the repository** (if you haven't already) |
| 13 | + |
| 14 | +2. **Install dependencies:** |
| 15 | + |
| 16 | + ```bash |
| 17 | + yarn install |
| 18 | + ``` |
| 19 | + |
| 20 | +3. **Build the TypeScript source:** |
| 21 | + |
| 22 | + ```bash |
| 23 | + yarn prepack |
| 24 | + ``` |
| 25 | + |
| 26 | + This command: |
| 27 | + |
| 28 | + - Compiles TypeScript from `src/` to `lib/` |
| 29 | + - Generates the oclif manifest |
| 30 | + - Updates the README with command documentation |
| 31 | + |
| 32 | +## Running Locally |
| 33 | + |
| 34 | +You have several options for running the CLI during development: |
| 35 | + |
| 36 | +### Option 1: Direct execution via bin/run |
| 37 | + |
| 38 | +```bash |
| 39 | +./bin/run [command] |
| 40 | +``` |
| 41 | + |
| 42 | +Example: |
| 43 | + |
| 44 | +```bash |
| 45 | +./bin/run --help |
| 46 | +./bin/run init |
| 47 | +./bin/run make model |
| 48 | +``` |
| 49 | + |
| 50 | +### Option 2: Create a development alias (recommended) |
| 51 | + |
| 52 | +Add an alias to your shell configuration file without affecting existing installations: |
| 53 | + |
| 54 | +**For zsh** (add to `~/.zshrc`): |
| 55 | + |
| 56 | +```bash |
| 57 | +alias fl-dev='/path/to/cli/bin/run' |
| 58 | +``` |
| 59 | + |
| 60 | +**For bash** (add to `~/.bashrc` or `~/.bash_profile`): |
| 61 | + |
| 62 | +```bash |
| 63 | +alias fl-dev='/path/to/cli/bin/run' |
| 64 | +``` |
| 65 | + |
| 66 | +After adding the alias, reload your shell: |
| 67 | + |
| 68 | +```bash |
| 69 | +source ~/.zshrc # or source ~/.bashrc |
| 70 | +``` |
| 71 | + |
| 72 | +Then use: |
| 73 | + |
| 74 | +```bash |
| 75 | +fl-dev [command] |
| 76 | +``` |
| 77 | + |
| 78 | +This allows you to keep your existing `fl1`, `fl2`, etc. aliases intact while having a dedicated `fl-dev` for local development. |
| 79 | + |
| 80 | +### Option 3: Link globally for development |
| 81 | + |
| 82 | +```bash |
| 83 | +yarn link |
| 84 | +``` |
| 85 | + |
| 86 | +After linking, you can use any of these commands: |
| 87 | + |
| 88 | +- `flarum-cli [command]` |
| 89 | +- `fl [command]` |
| 90 | +- `fl2 [command]` |
| 91 | + |
| 92 | +**Warning:** This will override any globally installed version of `@flarum/cli`. |
| 93 | + |
| 94 | +## Development Workflow |
| 95 | + |
| 96 | +### Making Changes |
| 97 | + |
| 98 | +1. **Edit TypeScript source files** in `src/` |
| 99 | +2. **Rebuild the project:** |
| 100 | + ```bash |
| 101 | + yarn prepack |
| 102 | + ``` |
| 103 | +3. **Test your changes:** |
| 104 | + ```bash |
| 105 | + ./bin/run [command] |
| 106 | + ``` |
| 107 | + |
| 108 | +### Testing |
| 109 | + |
| 110 | +Run the test suite: |
| 111 | + |
| 112 | +```bash |
| 113 | +yarn test |
| 114 | +``` |
| 115 | + |
| 116 | +This will: |
| 117 | + |
| 118 | +- Run Jest tests |
| 119 | +- Check code formatting with Prettier |
| 120 | +- Lint code with ESLint |
| 121 | +- Perform a TypeScript dry-run build |
| 122 | + |
| 123 | +### Code Formatting |
| 124 | + |
| 125 | +Format code automatically: |
| 126 | + |
| 127 | +```bash |
| 128 | +yarn format |
| 129 | +``` |
| 130 | + |
| 131 | +This runs ESLint with auto-fix and Prettier. |
| 132 | + |
| 133 | +## Project Structure |
| 134 | + |
| 135 | +``` |
| 136 | +. |
| 137 | +├── bin/ # Executable entry points |
| 138 | +│ └── run # Main CLI entry point |
| 139 | +├── src/ # TypeScript source code |
| 140 | +│ ├── commands/ # CLI command definitions |
| 141 | +│ ├── steps/ # Reusable step implementations |
| 142 | +│ ├── boilersmith/ # Scaffolding system |
| 143 | +│ └── base-command.ts # Base command class |
| 144 | +├── lib/ # Compiled JavaScript (gitignored) |
| 145 | +├── test/ # Test files |
| 146 | +├── boilerplate/ # Scaffolding templates |
| 147 | +├── stubs/ # Code generation templates |
| 148 | +├── php-subsystem/ # PHP parser for extend.php |
| 149 | +└── package.json |
| 150 | +``` |
| 151 | + |
| 152 | +## Architecture Overview |
| 153 | + |
| 154 | +### Technology Stack |
| 155 | + |
| 156 | +- **oclif**: CLI framework |
| 157 | +- **TypeScript**: Primary language |
| 158 | +- **PHP subsystem**: Uses `nikic/php-parser` for PHP code manipulation |
| 159 | +- **mem-fs**: In-memory filesystem for atomic operations |
| 160 | + |
| 161 | +### Key Concepts |
| 162 | + |
| 163 | +**Commands** (in `src/commands/`) |
| 164 | + |
| 165 | +- User-facing CLI commands |
| 166 | +- Built on oclif framework |
| 167 | +- Orchestrate step execution |
| 168 | + |
| 169 | +**Steps** (in `src/steps/`) |
| 170 | + |
| 171 | +- Granular, reusable operations |
| 172 | +- Modify in-memory filesystem |
| 173 | +- Can be composed atomically |
| 174 | +- Support parameter sharing between steps |
| 175 | + |
| 176 | +**Step Manager** |
| 177 | + |
| 178 | +- Fluent API for chaining steps |
| 179 | +- Handles optional steps |
| 180 | +- Manages parameter passing between steps |
| 181 | +- Supports atomic groups for transactional changes |
| 182 | + |
| 183 | +**Scaffolding System** (`src/boilersmith/`) |
| 184 | + |
| 185 | +- Manages extension infrastructure modules |
| 186 | +- Supports initialization and updates |
| 187 | +- Module-based file and config ownership |
| 188 | + |
| 189 | +## Debugging |
| 190 | + |
| 191 | +### Running with Node Inspector |
| 192 | + |
| 193 | +```bash |
| 194 | +node --inspect ./bin/run [command] |
| 195 | +``` |
| 196 | + |
| 197 | +### Verbose Output |
| 198 | + |
| 199 | +Most commands support flags for additional output. Check command help: |
| 200 | + |
| 201 | +```bash |
| 202 | +./bin/run [command] --help |
| 203 | +``` |
| 204 | + |
| 205 | +## Common Tasks |
| 206 | + |
| 207 | +### Adding a New Command |
| 208 | + |
| 209 | +1. Create command file in `src/commands/` |
| 210 | +2. Extend from `BaseCommand` class |
| 211 | +3. Define steps using Step Manager |
| 212 | +4. Rebuild with `yarn prepack` |
| 213 | +5. Test with `./bin/run [your-command]` |
| 214 | + |
| 215 | +### Adding a New Step |
| 216 | + |
| 217 | +1. Create step class in appropriate `src/steps/` subdirectory |
| 218 | +2. Implement required methods (`run`, `getExposedParams`, etc.) |
| 219 | +3. Add unit tests |
| 220 | +4. Use step in command's `steps()` method |
| 221 | + |
| 222 | +### Updating Boilerplate Templates |
| 223 | + |
| 224 | +1. Edit files in `boilerplate/skeleton/extension/` |
| 225 | +2. Update module definitions in scaffolding system |
| 226 | +3. Test with `./bin/run init` or `./bin/run infra` |
| 227 | + |
| 228 | +## Troubleshooting |
| 229 | + |
| 230 | +### "Command not found" after changes |
| 231 | + |
| 232 | +- Ensure you've run `yarn prepack` to rebuild |
| 233 | +- Check that `lib/` directory exists and contains compiled code |
| 234 | + |
| 235 | +### TypeScript errors |
| 236 | + |
| 237 | +- Run `yarn posttest` to see type checking output |
| 238 | +- Ensure `tsconfig.json` includes your new files |
| 239 | + |
| 240 | +### Tests failing |
| 241 | + |
| 242 | +- Run `yarn test` to see full output |
| 243 | +- Check that step unit tests match your changes |
| 244 | + |
| 245 | +## Contributing |
| 246 | + |
| 247 | +When making changes: |
| 248 | + |
| 249 | +1. Follow existing code patterns |
| 250 | +2. Add unit tests for new steps and functionality |
| 251 | +3. Update documentation as needed |
| 252 | +4. Run `yarn format` before committing |
| 253 | +5. Ensure `yarn test` passes |
| 254 | + |
| 255 | +## Additional Resources |
| 256 | + |
| 257 | +- [oclif Documentation](https://oclif.io/) |
| 258 | +- [README.md](README.md) - User-facing documentation |
| 259 | +- Main README "For Maintainers" section - Architecture deep-dive |
0 commit comments