feat: arr CLI

CLAUDE.md

@@ -46,9 +46,12 @@
 
 ### Avoid Barrel Files
 
+- Do not make use of index.ts
+
 Barrel files:
+
 - Break tree-shaking
-- Create circular dependency risks  
+- Create circular dependency risks
 - Hide the true source of imports
 - Make refactoring harder
 
@@ -74,6 +77,17 @@ See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed patterns (DI, services, tR
 - PostHog API integration in `posthog-api.ts`
 - Task execution and session management
 
+### CLI Package (packages/cli)
+
+- **Dumb shell, imperative core**: CLI commands should be thin wrappers that call `@array/core`
+- All business logic belongs in `@array/core`, not in CLI command files
+- CLI only handles: argument parsing, calling core, formatting output
+- No data transformation, tree building, or complex logic in CLI
+
+### Core Package (packages/core)
+
+- Shared business logic for jj/GitHub operations
+
 ## Key Libraries
 
 - React 18, Radix UI Themes, Tailwind CSS
@@ -91,6 +105,5 @@ TODO: Update me
 
 ## Testing
 
-- Tests use vitest with jsdom environment
-- Test helpers in `src/test/`
-- Run specific test: `pnpm --filter array test -- path/to/test`
+- `pnpm test` - Run tests across all packages
+- Array app: Vitest with jsdom, helpers in `apps/array/src/test/`

apps/cli/README.md

@@ -0,0 +1,93 @@
+> [!IMPORTANT] > `arr` is still in development and not production-ready. Interested? Email jonathan@posthog.com
+
+# arr
+
+arr is CLI for stacked PR management using Jujutsu (`jj`).
+
+Split your work into small changes, push them as a PR stack, and keep everything in sync.
+
+## Install
+
+Requires [Bun](https://bun.sh).
+
+```
+git clone https://github.com/posthog/array
+cd array
+pnpm install
+pnpm --filter @array/core build
+```
+
+Then install the `arr` command (symlinked to `~/bin/arr`):
+
+```
+./apps/cli/arr.sh install
+```
+
+## Usage
+
+```
+arr init                # set up arr in a git repo
+arr create "message"    # new change on stack
+arr submit              # push stack, create PRs
+arr merge               # merge stack of PRs
+arr sync                # fetch, rebase, cleanup merged
+arr up / arr down       # navigate stack
+arr log                 # show stack
+arr exit                # back to git
+arr help --all          # show all commands
+```
+
+## Example
+
+```
+$ echo "user model" >> user_model.ts
+$ arr create "Add user model"
+✓ Created add-user-model-qtrsqm
+
+$ echo "user api" >> user_api.ts
+$ arr create "Add user API"
+✓ Created add-user-api-nnmzrt
+
+$ arr log
+◉ (working copy)
+│ Empty
+○ 12-23-add-user-api nnmzrtzz (+1, 1 file)
+│ Not submitted
+○ 12-23-add-user-model qtrsqmmy (+1, 1 file)
+│ Not submitted
+○ main
+
+$ arr submit
+Created PR #8: 12-23-add-user-model
+  https://github.com/username/your-repo/pull/8
+Created PR #9: 12-23-add-user-api
+  https://github.com/username/your-repo/pull/9
+
+$ arr merge
+...
+
+$ arr sync
+```
+
+Each change becomes a PR. 
+Stacked PRs are explained through a generated comments so reviewers see the dependency.
+
+## FAQ
+
+**Can I use this with an existing `git` repo?**
+
+Yes, do so by using `arr init` in any `git` repo. `jj` works alongside `git`.
+
+**Do my teammates need to use `arr` or `jj`?**
+
+No, your PRs are normal GitHub PRs. Teammates review and merge them as usual. `jj` has full support for `git`.
+
+**What if I want to stop using `arr`?**
+
+Run `arr exit` to switch back to `git`. Your repo, branches, and PRs stay exactly as they are.
+
+## Learn more
+
+- [`jj` documentation](https://jj-vcs.github.io/jj/latest/) - full `jj` reference
+- [`jj` tutorial](https://jj-vcs.github.io/jj/latest/tutorial/) - getting started with `jj`
+- `arr help`

apps/cli/arr.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Wrapper script to run arr CLI via bun.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+
+# Self-install: ./arr.sh install
+if [ "$1" = "install" ]; then
+  mkdir -p ~/bin
+  ln -sf "$SCRIPT_DIR/arr.sh" ~/bin/arr
+  echo "Installed: ~/bin/arr -> $SCRIPT_DIR/arr.sh"
+  echo "Make sure ~/bin is in your PATH"
+  exit 0
+fi
+
+exec bun run "$SCRIPT_DIR/bin/arr.ts" "$@"

apps/cli/bin/arr.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+
+import { main } from "../src/cli";
+
+main()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

apps/cli/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@array/cli",
+  "version": "0.0.1",
+  "description": "CLI for changeset management with jj",
+  "bin": {
+    "arr": "./bin/arr.ts"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "dev": "bun run ./bin/arr.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test --concurrent tests/unit tests/e2e/cli.test.ts",
+    "test:pty": "vitest run tests/e2e/pty.test.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@array/core": "workspace:*"
+  }
+}