docs: README EN/FR — refonte « IDE worktree » (P7→P12)
Workspace IDE (arbre + Monaco + diff + terminal), moteur git détaillé + watcher FS temps réel, commit/push avancé, archivage auto des sessions, sync des réglages en temps réel, services git distants chiffrés + clone. Section VS Code mise à jour (fetch/pull, lien IDE web, VSIX 0.2.0).
This commit is contained in:
42
README.md
42
README.md
@@ -12,6 +12,8 @@
|
||||
|
||||
**Status: MVP.** The worktree-first dashboard, session discovery & resume, multi-repo worktree lifecycle, sessions on your main branch or any worktree, live session states, the web terminal, mobile supervision (installable PWA, Web Push when a session needs you, answer a prompt without opening a terminal), and work groups (drive several related repos from a single Claude session) are implemented and tested.
|
||||
|
||||
The latest milestone turns Arboretum into a real **worktree IDE**: an in-browser workspace (file tree, Monaco editor, inline diffs, integrated terminal), detailed git status backed by a real-time file-system watcher, selective staging / discard / amend / fetch / pull, automatic session archival, real-time settings sync across browsers, and encrypted remote git services (GitHub / GitLab / Gitea) with HTTPS clone.
|
||||
|
||||
---
|
||||
|
||||
## The problem
|
||||
@@ -30,8 +32,11 @@ A single Node.js daemon you run on your dev machine (`npx @johanleroy/git-arbore
|
||||
- **Full worktree lifecycle** — create (with per-repo post-create hooks: `npm ci`, copy `.env`…), adopt worktrees created by hand, delete with guardrails, prune orphans.
|
||||
- **Session discovery & resume** — sessions you launched in your own terminal show up automatically; resume dead ones, observe or fork live ones. Never corrupts a live session. Hide the old ones that clutter the list (one click clears the whole external history; they stay resumable).
|
||||
- **Web terminal** — full xterm.js terminal to every managed session, surviving browser disconnects; truly fullscreen, with the prompt pinned to the bottom and full scrollback above.
|
||||
- **Worktree IDE** — open any worktree in a full in-browser workspace: a file tree, a Monaco editor, an inline per-file diff viewer and the worktree's session terminal, side by side. Edit files, stage changes selectively, commit (or amend), fetch/pull and push — all without leaving the dashboard. A real-time file-system watcher keeps the view live as the agent edits.
|
||||
- **Supervision from your phone** — installable PWA with push notifications when a session needs you; answer a prompt (its options, or deny) without opening a terminal.
|
||||
- **Work groups** — bundle related repos (e.g. an API, its web frontend and its docs) into a named group, then launch **one Claude session that spans all of them at once** (via the CLI's `--add-dir`): a single conversation with one shared context working across every repo, plus a unified view of all their worktrees and a side-by-side multi-terminal grid. Group sessions can either create the same branch worktree in each repo first, or run straight on the main checkouts.
|
||||
- **Remote git services** — connect your GitHub, GitLab or Gitea accounts (personal access token or app password), stored **encrypted at rest** (AES-256-GCM); browse your remote repositories and clone them over HTTPS with live progress, straight from the dashboard.
|
||||
- **Automatic archival** — finished sessions are archived automatically after a configurable retention window (30 days by default), so the list stays focused on what's live while the history is one toggle away.
|
||||
- **VS Code extension** — a native extension (not a webview) that brings the live tree, native session terminals, waiting alerts and git actions right into your editor. See [VS Code extension](#vs-code-extension).
|
||||
|
||||
---
|
||||
@@ -105,6 +110,18 @@ node packages/server/dist/index.js
|
||||
4. **Watch the live states.** Each session reports whether it's *busy*, *waiting for your input*, or *idle*. Open the **web terminal** to interact directly; it survives browser disconnects (closing the tab does not kill the session).
|
||||
5. **Supervise from your phone.** Install the PWA, and when a session flips to *waiting* you get a push notification. Answer the prompt — pick one of its options or deny it — straight from the dashboard, no terminal required.
|
||||
|
||||
## Workspace & git operations
|
||||
|
||||
Beyond supervising, Arboretum lets you actually *work* on a worktree from the browser. Open any worktree's **workspace** (`/workspace`) for an IDE-like, three-pane view:
|
||||
|
||||
- **File tree & editor.** Browse the worktree, open a file in a **Monaco editor** (syntax highlighting, language detection), edit and save it. Binary and oversized files are handled gracefully.
|
||||
- **Per-file diffs.** A unified diff viewer shows exactly what changed, line by line, for the working tree or the index — additions and deletions colour-coded, with a refusal to render binary or huge diffs.
|
||||
- **Selective staging & commit.** Stage or unstage individual files, discard changes you don't want, write a message and **commit** — either everything (`git add -A`) or just what's staged. **Amend** the last commit (refused once it's been pushed), then **fetch**, **pull** (fast-forward or rebase) and **push**.
|
||||
- **Detailed git status.** Every worktree reports staged / unstaged / conflict counts and its last commit, kept current by a **real-time file-system watcher** so the diff and counts update the moment a Claude session touches a file.
|
||||
- **Integrated terminal.** The worktree's correlated Claude session terminal sits right next to the editor, so you can read the diff and talk to the agent in one place.
|
||||
|
||||
Like every git action in Arboretum, these run **as you** (the daemon runs under your account) — consistent with the security model: a web terminal is remote code execution by design.
|
||||
|
||||
## VS Code extension
|
||||
|
||||
Prefer to stay in your editor? Arboretum ships a **native VS Code extension** (`packages/vscode`) — not a webview. It connects to the same daemon and surfaces it with VS Code's own primitives:
|
||||
@@ -112,16 +129,17 @@ Prefer to stay in your editor? Arboretum ships a **native VS Code extension** (`
|
||||
- A live **Repositories** and **Groups** tree (repos → worktrees → sessions) in the Activity Bar, updated in real time over the daemon's WebSocket.
|
||||
- **Native terminals**: attach to (or observe) any session in a real VS Code terminal — you get VS Code's rendering, scrollback and copy/paste for free.
|
||||
- A **status-bar** counter and native **notifications** when a session is waiting, with Yes/No answers without opening a terminal.
|
||||
- Git mutations (create worktree, commit, push, promote) and **workspace awareness** — the worktree for your open folder is highlighted, with one-click "start session / create worktree here".
|
||||
- Git mutations (create worktree, commit, push, promote, **fetch / pull**) with **detailed git status** in the tree (staged / unstaged / conflicts and the last commit), and **workspace awareness** — the worktree for your open folder is highlighted, with one-click "start session / create worktree here".
|
||||
- **Open in the web IDE** — jump from any worktree straight to its full `/workspace` view in the browser. The extension stays a lightweight, visual worktree manager; the heavy editing lives in the web IDE.
|
||||
|
||||
It is distributed as a **private VSIX**. Build and package it from the monorepo:
|
||||
|
||||
```bash
|
||||
npm run build:vscode
|
||||
cd packages/vscode && npx @vscode/vsce package --no-dependencies # → git-arboretum-0.1.0.vsix
|
||||
cd packages/vscode && npx @vscode/vsce package --no-dependencies # → git-arboretum-0.2.0.vsix
|
||||
```
|
||||
|
||||
Then install it via **Extensions: Install from VSIX…** (or `code --install-extension git-arboretum-0.1.0.vsix`), run **Arboretum: Sign In** and paste a token. Full details in [`packages/vscode/README.md`](packages/vscode/README.md).
|
||||
Then install it via **Extensions: Install from VSIX…** (or `code --install-extension git-arboretum-0.2.0.vsix`), run **Arboretum: Sign In** and paste a token. Full details in [`packages/vscode/README.md`](packages/vscode/README.md).
|
||||
|
||||
## Remote access from your phone
|
||||
|
||||
@@ -221,6 +239,16 @@ Daemon options are CLI flags:
|
||||
|
||||
State (the SQLite database) lives in `$XDG_DATA_HOME/arboretum` (default `~/.local/share/arboretum`).
|
||||
|
||||
Settings beyond CLI flags — the directories Arboretum scans for repos and how often, the `claude` binary path and home, and the session retention / purge windows — live in **Settings** in the UI. They are broadcast over the WebSocket, so every connected browser reflects a change in real time, no reload needed.
|
||||
|
||||
## Remote git services & clone
|
||||
|
||||
Arboretum can connect to your git hosting providers so you can browse and clone repositories without leaving the dashboard:
|
||||
|
||||
- **Providers & auth.** GitHub, GitLab and Gitea, authenticated with a **personal access token** or an **app password** (SSH keys and OAuth are planned). Add a connection from **Settings → Git services**, give it a label, and test it in place — Arboretum reports `ok`, `auth failed`, `rate limited` or `unreachable`.
|
||||
- **Secrets stay secret.** Credentials are **encrypted at rest** (AES-256-GCM, `SecretBox`) and **never** returned in clear by the REST API — responses carry only a `…last4` hint and a "has secret" flag.
|
||||
- **Browse & clone.** List the repositories a connection can see, pick one, and clone it over HTTPS into a destination of your choice. The clone runs as a tracked operation with live **progress and phase** pushed over the WebSocket, and the new repo is registered automatically when it completes.
|
||||
|
||||
## Security model
|
||||
|
||||
A web terminal is remote code execution *by design*. Arboretum's guardrails are structural:
|
||||
@@ -272,8 +300,16 @@ node packages/server/scripts/acceptance-p2.mjs # session discovery & resume
|
||||
node packages/server/scripts/acceptance-p3.mjs # worktrees & session correlation
|
||||
node packages/server/scripts/acceptance-p4.mjs # Web Push + WS `answer` command
|
||||
node packages/server/scripts/acceptance-p5.mjs # work groups: CRUD + WS broadcast + CASCADE
|
||||
node packages/server/scripts/acceptance-p7.mjs # git engine, file API & real-time FS watcher
|
||||
node packages/server/scripts/acceptance-p8.mjs # workspace IDE: changes / diff / staging / commit
|
||||
node packages/server/scripts/acceptance-p9.mjs # advanced commit/push: selective staging, amend, fetch/pull
|
||||
node packages/server/scripts/acceptance-p10.mjs # automatic session archival
|
||||
node packages/server/scripts/acceptance-p11.mjs # real-time settings sync
|
||||
node packages/server/scripts/acceptance-p12.mjs # remote git services + HTTPS clone
|
||||
```
|
||||
|
||||
The protocol grew (additively, no version bump) to carry the new surface: client `watch` / `unwatch` messages and the targeted `worktree_changes` signal (P7), plus `session_archived` (P10), `settings_update` (P11) and `clone_update` (P12) broadcasts. Server-side, the work is backed by `core/git.ts` (the pure git engine), `core/fs-watcher.ts` (chokidar), `core/git-credentials.ts` + `core/clone-manager.ts` (encrypted credentials & clone), and the session-archive and settings services.
|
||||
|
||||
## Support
|
||||
|
||||
Arboretum is a free, self-funded side project. If it saves you time, you can support its development:
|
||||
|
||||
Reference in New Issue
Block a user