Skip to content

Commit fc3b076

Browse files
authored
fix: cannot split on apple silicon (#47)
* fix: cannot split on apple silicon * chore: format * chore: bump version
1 parent 4f706c0 commit fc3b076

8 files changed

Lines changed: 272 additions & 5 deletions

File tree

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@
55
/tmp
66
node_modules
77
coverage
8+
oclif.manifest.json

DEVELOPING.md

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
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

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ $ npm install -g @flarum/cli
4949
$ flarum-cli COMMAND
5050
running command...
5151
$ flarum-cli (-v|--version|version)
52-
@flarum/cli/3.0.11 linux-x64 node-v18.19.1
52+
@flarum/cli/3.0.11-dev darwin-arm64 node-v25.1.0
5353
$ flarum-cli --help [COMMAND]
5454
USAGE
5555
$ flarum-cli COMMAND

bin/libgit2.1.5.dylib

1.91 MB
Binary file not shown.

bin/splitsh-lite-darwin-arm64

9.86 MB
Binary file not shown.

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@flarum/cli",
33
"description": "A CLI for developing Flarum extensions",
4-
"version": "3.0.11",
4+
"version": "3.0.12-dev",
55
"author": "Flarum Team",
66
"flarum": "2.x",
77
"bin": {

src/steps/monorepo/split.ts

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ export class MonorepoSplit implements Step<FlarumProviders> {
6464

6565
async run(fs: Store, paths: Paths, io: IO, _providers: FlarumProviders): Promise<Store> {
6666
const platform = process.platform;
67+
const arch = process.arch;
68+
6769
if (platform !== 'linux' && platform !== 'darwin') {
6870
io.error(`Your platform, "${platform}", is not supported. Split can only be run on linux and mac`, true);
6971
return fs;
@@ -74,7 +76,12 @@ export class MonorepoSplit implements Step<FlarumProviders> {
7476
return fs;
7577
}
7678

77-
const splitExec = resolve(__dirname, `../../../bin/splitsh-lite-${platform}`);
79+
// Select the appropriate binary based on platform and architecture
80+
let splitExec: string;
81+
splitExec =
82+
platform === 'darwin' && arch === 'arm64'
83+
? resolve(__dirname, `../../../bin/splitsh-lite-darwin-arm64`)
84+
: resolve(__dirname, `../../../bin/splitsh-lite-${platform}`);
7885

7986
const target = paths.requestedDir() ?? paths.package();
8087

src/steps/upgrade/twopointoh/dependencies.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,8 +102,8 @@ export default class Dependencies extends BaseUpgradeStep {
102102
'flarum-webpack-config': '^3.0.0',
103103
'flarum-tsconfig': '^2.0.0',
104104
'@flarum/jest-config': '^2.0.0',
105-
'webpack': "^5.65.0",
106-
'webpack-cli': "^4.9.1",
105+
webpack: '^5.65.0',
106+
'webpack-cli': '^4.9.1',
107107
};
108108

109109
const dependencies = advanced.dependencies || advanced.devDependencies;

0 commit comments

Comments
 (0)