Skip to content

Commit 5c28359

Browse files
jonathanlabjonathanlab
committed
squash
1 parent ac67cf8 commit 5c28359

130 files changed

Lines changed: 12778 additions & 50 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CLAUDE.md‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,12 @@
4646

4747
### Avoid Barrel Files
4848

49+
- Do not make use of index.ts
50+
4951
Barrel files:
52+
5053
- Break tree-shaking
51-
- Create circular dependency risks
54+
- Create circular dependency risks
5255
- Hide the true source of imports
5356
- Make refactoring harder
5457

@@ -74,6 +77,17 @@ See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed patterns (DI, services, tR
7477
- PostHog API integration in `posthog-api.ts`
7578
- Task execution and session management
7679

80+
### CLI Package (packages/cli)
81+
82+
- **Dumb shell, imperative core**: CLI commands should be thin wrappers that call `@array/core`
83+
- All business logic belongs in `@array/core`, not in CLI command files
84+
- CLI only handles: argument parsing, calling core, formatting output
85+
- No data transformation, tree building, or complex logic in CLI
86+
87+
### Core Package (packages/core)
88+
89+
- Shared business logic for jj/GitHub operations
90+
7791
## Key Libraries
7892

7993
- React 18, Radix UI Themes, Tailwind CSS
@@ -91,6 +105,5 @@ TODO: Update me
91105

92106
## Testing
93107

94-
- Tests use vitest with jsdom environment
95-
- Test helpers in `src/test/`
96-
- Run specific test: `pnpm --filter array test -- path/to/test`
108+
- `pnpm test` - Run tests across all packages
109+
- Array app: Vitest with jsdom, helpers in `apps/array/src/test/`

‎apps/cli/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
> [!IMPORTANT] > `arr` is still in development and not production-ready. Interested? Email jonathan@posthog.com
2+
3+
# arr
4+
5+
arr is CLI for stacked PR management using Jujutsu (`jj`).
6+
7+
Split your work into small changes, push them as a PR stack, and keep everything in sync.
8+
9+
## Features
10+
11+
- Stacked PRs synced to GitHub
12+
- Simpler interface compared to `jj` for managing your work.
13+
- Visual stack log with PR status.
14+
- Comes with a GitHub Action to enforce merge order
15+
- Unknown commands pass through to `jj`
16+
17+
## Why
18+
19+
Stacked PRs keep reviews small and manageable. Managing them with `git` is painful, this involves rebasing, force-pushing, updating PR bases and describing the PR stack via comments.
20+
21+
`arr` makes it easy to create, manage and submit (stacked) PRs by using `jj` under the hood.
22+
23+
## Install
24+
25+
Requires [Bun](https://bun.sh).
26+
27+
```
28+
git clone https://github.com/posthog/array
29+
cd array
30+
pnpm install
31+
pnpm --filter @array/core build
32+
```
33+
34+
Then install the `arr` command (symlinked to `~/bin/arr`):
35+
36+
```
37+
./apps/cli/arr.sh install
38+
```
39+
40+
## Usage
41+
42+
```
43+
arr init # set up arr in a git repo
44+
arr create "message" # new change on stack
45+
arr submit # push stack, create PRs
46+
arr merge # merge PR via GitHub
47+
arr sync # fetch, rebase, cleanup merged
48+
arr up / arr down # navigate stack
49+
arr log # show stack
50+
arr exit # back to git
51+
arr help --all # show all commands
52+
```
53+
54+
## Example
55+
56+
```
57+
$ echo "user model" >> user_model.ts
58+
$ arr create "Add user model"
59+
✓ Created add-user-model-qtrsqm
60+
61+
$ echo "user api" >> user_api.ts
62+
$ arr create "Add user API"
63+
✓ Created add-user-api-nnmzrt
64+
65+
$ arr log
66+
◉ (working copy)
67+
│ Empty
68+
○ 12-23-add-user-api nnmzrtzz (+1, 1 file)
69+
│ Not submitted
70+
○ 12-23-add-user-model qtrsqmmy (+1, 1 file)
71+
│ Not submitted
72+
○ main
73+
74+
$ arr submit
75+
Created PR #8: 12-23-add-user-model
76+
https://github.com/username/your-repo/pull/8
77+
Created PR #9: 12-23-add-user-api
78+
https://github.com/username/your-repo/pull/9
79+
80+
$ arr merge
81+
...
82+
83+
$ arr sync
84+
```
85+
86+
Each change becomes a PR. PRs are stacked so reviewers see the dependency.
87+
88+
## CI
89+
90+
```
91+
arr ci
92+
```
93+
94+
Adds a GitHub Action that blocks merging a PR if its parent PR hasn't merged yet, which helps keep your stack in order.
95+
96+
## FAQ
97+
98+
**Can I use this with an existing `git` repo?**
99+
100+
Yes, do so by using `arr init` in any `git` repo. `jj` works alongside `git`.
101+
102+
**Do my teammates need to use `arr` or `jj`?**
103+
104+
No, your PRs are normal GitHub PRs. Teammates review and merge them as usual. `jj` has full support for `git`.
105+
106+
**What if I want to stop using `arr`?**
107+
108+
Run `arr exit` to switch back to `git`. Your repo, branches, and PRs stay exactly as they are.
109+
110+
**How is `arr` related to Array?**
111+
112+
`arr` is the CLI component of Array, an agentic development environment.
113+
114+
## Learn more
115+
116+
- [`jj` documentation](https://jj-vcs.github.io/jj/latest/) - full `jj` reference
117+
- [`jj` tutorial](https://jj-vcs.github.io/jj/latest/tutorial/) - getting started with `jj`

‎apps/cli/arr.sh‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#!/usr/bin/env bash
2+
# Wrapper script to run arr CLI via bun.
3+
SOURCE="${BASH_SOURCE[0]}"
4+
while [ -L "$SOURCE" ]; do
5+
DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
6+
SOURCE="$(readlink "$SOURCE")"
7+
[[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
8+
done
9+
SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
10+
11+
# Self-install: ./arr.sh install
12+
if [ "$1" = "install" ]; then
13+
mkdir -p ~/bin
14+
ln -sf "$SCRIPT_DIR/arr.sh" ~/bin/arr
15+
echo "Installed: ~/bin/arr -> $SCRIPT_DIR/arr.sh"
16+
echo "Make sure ~/bin is in your PATH"
17+
exit 0
18+
fi
19+
20+
exec bun run "$SCRIPT_DIR/bin/arr.ts" "$@"

‎apps/cli/bin/arr.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/usr/bin/env bun
2+
3+
import { main } from "../src/cli";
4+
5+
main()
6+
.then(() => process.exit(0))
7+
.catch((error) => {
8+
console.error(error);
9+
process.exit(1);
10+
});

‎apps/cli/package.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"name": "@array/cli",
3+
"version": "0.0.1",
4+
"description": "CLI for changeset management with jj",
5+
"bin": {
6+
"arr": "./bin/arr.ts"
7+
},
8+
"type": "module",
9+
"scripts": {
10+
"build": "bun build ./src/index.ts --outdir ./dist --target bun",
11+
"dev": "bun run ./bin/arr.ts",
12+
"typecheck": "tsc --noEmit",
13+
"test": "bun test --concurrent tests/unit tests/e2e/cli.test.ts",
14+
"test:pty": "vitest run tests/e2e/pty.test.ts"
15+
},
16+
"devDependencies": {
17+
"@types/bun": "latest",
18+
"@types/node": "^25.0.3",
19+
"typescript": "^5.5.0",
20+
"vitest": "^4.0.16"
21+
},
22+
"dependencies": {
23+
"@array/core": "workspace:*"
24+
}
25+
}

0 commit comments

Comments
 (0)