naps62/maestro
Archived
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into dominant

Browse Source
This commit is contained in:
Miguel Palhas
2026-09-03 14:06:58 +01:00
parent cd37ac5d6d b0504eb736
commit b46ba9dd26
11 changed files with 941 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/COMMAND-BAR.md
+479
View File
@@ -0,0 +1,479 @@
# COMMAND-BAR.md — the command bar contract
One rule for the `ctrl-k` command bar in both clients, so the web bar and the
TUI bar open the same way, rank the same results in the same order, and act on
the same keys. Read this before changing either. Both clients implement exactly
what is written here; if the behaviour needs to change, change it here first.
The bar is one surface with three jobs: **go to a session**, **run a command**,
**spawn into a directory**. It is not a new place to configure anything and it
does not own any action — it chooses one and hands off to the flow that already
implements it.
## Opening
`ctrl-k` opens the bar from anywhere:
| Client | From | Notes |
| --- | --- | --- |
| TUI | Normal mode | Sidebar has the keyboard. |
| TUI | Insert mode | The pane has the keyboard; the bar still opens. |
| Web | Sidebar focused | Ordinary global binding. |
| Web | Terminal focused | Intercepted before xterm sees it. |
It is a **keymap entry like any other**, not a hard-wired key. In the TUI it is
bound in both `DEFAULT_NORMAL` and `DEFAULT_INSERT` and is rebindable through
`[tui.keymap.*]`; because the help overlay builds its lines from the live
keymap, it appears there without a second list to maintain. In the web it is an
entry in the command registry, so the `?` overlay lists it for the same reason.
An attached xterm swallows every keystroke it is given, so the web binding is
handled in the **capture phase**, ahead of the terminal — the same way the
restart overlay swallows the app's shortcuts (`docs/RESTART.md`).
### Escape hatch — sending a literal Ctrl-K
Binding `ctrl-k` takes readline's kill-to-end-of-line away from every pane. The
leader gives it back: **leader then `ctrl-k`** — `ctrl-a ctrl-k` by default —
sends the literal `0x0B` byte to the focused pane and does not open the bar.
The TUI already has a leader (`ctrl-a`, `[tui].leader`), and this chord goes
through the existing chord resolution, so rebinding the leader rebinds the
escape hatch with it — exactly as the leader's Insert-mode escape already
works. **The web gains a leader for this**, defaulting to `ctrl-a` and
mirroring the TUI's. `ctrl-a` is select-all in a browser; the web
`preventDefault`s it, since selecting all of a terminal pane does nothing
useful.
Only Ctrl-K gets an escape hatch. No other control character is intercepted, so
none of them needs one.
### Focus round-trip
Closing the bar returns the keyboard to whatever held it when the bar opened,
the terminal included. A round trip through the bar never silently moves focus,
and never counts as a focus change for the daemon: opening the bar does not
report the pane unfocused, and closing it does not report a new focus. The bar
is a view over the app, not a place in it.
Opening the bar while a session is previewed (`docs/PREVIEW.md`) discards the
preview first, like any other real change; the bar is not previewed into.
## Structure
The bar is a query line over a result list. By default the list is **flat and
mixed** — sessions and commands ranked together — and rendered under **kind
headers**: a header row naming the kind, then that kind's results.
Grouping is a rendering of the ranking, never a reordering of it:
- Results are ranked as one list by the algorithm below.
- A kind's group holds its matches in that rank order.
- **Groups are ordered by their best-scoring member.** The first row under the
first header is therefore the globally best result, and the highlight starts
on it.
Two sigils, typed as the **first character** of the query, narrow the list to
one kind:
| Sigil | Kind | Candidates | Enter |
| --- | --- | --- | --- |
| `>` | commands | Every entry in the client's command registry — the web registry from the `?` overlay, the TUI's live `(chord, Action)` keymap for the current mode. | Runs the command. |
| `~` | directories | Recent dirs (`GET /api/recent-dirs`) and the project list the spawn form already uses, with `GET /api/dirs` filling in as a path is typed. | Spawns a session there with every default resolved. |
While a sigil is in force there is one kind, so the kind header is dropped. A
command row shows its **key chord** beside its label, so the bar teaches the
keymap instead of replacing it. A `~` spawn takes the same fast-forward path as
`N` / `FastForwardSpawn`: an unresolvable default opens the pre-filled spawn
form rather than failing silently.
**Backspacing past a sigil returns to the mixed list.** The sigil is one
character of the query like any other — deleting it is not a special key, it is
the query becoming empty again.
The sigil is only a sigil in first position. `>` or `~` typed anywhere else is
a literal query character (a directory query is where a `~` is most likely to
be typed twice, and the second one must reach the matcher).
## Empty query
With no sigil and an empty query the bar lists **sessions only, most recently
focused first**, so `ctrl-k enter` is "back to where I just was". Commands and
directories need a sigil or a query to appear; an empty bar is a session
switcher.
**Recency comes from the daemon**, not from client state — the same order in
every client, on every device, including one that just loaded the page. The
daemon stamps a last-focused time per session and ships it on the session like
any other field (#145). Both of the ways focus moves stamp the same field: a
client opening `/api/attach/:id`, and a client reporting focus explicitly at
`POST /api/sessions/:id/focus` when it refocuses a pane that is already open.
**A session that has never been focused sorts after every session that has**,
and among those, most recently created first. Dead sessions sort after live
ones regardless of recency: a session you cannot attach to is not where you
just were.
Under `>` an empty query lists every command in registry order. Under `~` it
lists recent dirs, most recent first, then the project list.
## Keys
| Key | Action |
| --- | --- |
| `enter` | Open the highlighted result — attach the session, run the command, spawn into the directory. |
| `tab` | Drill into the highlighted **session**'s action page. No effect on any other kind. |
| `esc` | At the top level, close the bar. On an action page, return to the result list. |
| `backspace` | Ordinary editing; at an empty query on an action page, return to the result list. |
| `up` / `down` | Move the highlight. |
| `ctrl-p` / `ctrl-n` | Move the highlight. |
The highlight does not wrap: it stops at the first and last row. Kind headers
are never landed on — they are labels, not rows.
Enter on a session goes through the **same open path** the sidebar's click and
the hash router already share, so a bar attach can never leave the layout in a
state a click could not produce.
### Drill-in — the session action page
`tab` on a highlighted session opens that session's action page inside the same
overlay: **kill**, **rename**, **spawn similar**. The page is still fuzzy
searchable — the query line keeps working, now over those actions.
- The overlay names the session being acted on, so the target is never
ambiguous.
- Escape, or backspace at an empty query, returns to the result list **with the
previous query intact**. Drilling in and backing out is free.
- Each action raises the flow it already has: kill goes through the existing
confirm-and-blockers dialog (`docs/WORKTREES.md`), rename through the
existing prompt pre-filled with the session's own name
(`docs/SIDEBAR.md`), spawn similar through the spawn form seeded from the
session's directory and command. The bar picks the action; it never
reimplements one.
No actions beyond those three, and no action across more than one session.
## Touch entry
On the web, **tapping or focusing the sidebar's search field opens the bar**
with an empty query. There is no `ctrl-k` on a phone and the product is
mobile-first, so the field the operator already reaches for is the entry point.
This **replaces** the sidebar's inline substring filter — one search affordance
in the header, not two beside each other. The tree's "No matches" empty state
belonged to that filter and goes with it; the bar's own no-results state takes
over (see the fixture `F4`).
At phone width the bar follows the bottom-sheet treatment the spawn modal
already uses below 600px. Visuals otherwise come from `DESIGN.md`'s existing
overlay tokens — the bar is the same family of surface as the spawn modal and
the help overlay, not a new one.
## What a candidate is
The matcher is a pure function: `(query, candidates) → ranked subset with
matched ranges`. It knows nothing about sessions, panes or the network. A
candidate is a **kind** plus a set of **named text fields**, each with a fixed
weight.
| Kind | Field | Weight | Text |
| --- | --- | --- | --- |
| session | `name` | `0` | The name as the sidebar shows it: `metadata.name` if set, else the command line (`docs/SIDEBAR.md`'s fallback). |
| session | `directory` | `-24` | The directory the sidebar groups it under, abbreviated: `~/dev/api`, not `/home/me/dev/api`. |
| session | `command` | `-32` | The full command line, arguments included. |
| session | `tool` | `-40` | The tool id the card's icon stands for (`claude`, `codex`, `opencode`, …), absent when the program is not one we have a mark for. |
| command | `label` | `0` | The plain-language label — the web registry's label, the TUI's `Action::help_label`. |
| directory | `path` | `0` | The path as displayed, abbreviated the same way. |
A command's **key chord is displayed, not matched**. It is there to teach the
keymap; matching it would make `>` results depend on a user's rebinds, and the
two clients do not share a keymap.
A candidate **matches** if at least one of its fields matches. Its score is the
**best** `field score + field weight` across its fields, and the matched ranges
it returns are those of that winning field — so a session found through its
directory highlights inside the directory, not inside its name.
## Match and rank
Two independent implementations (#146 in TypeScript, #147 in Rust) must produce
the same order for the same input. Everything below is exact.
### Normalization
- **Query**: lowercase, then remove every whitespace character. The result is
the *normalized query*. If it is empty, see "Empty query" below.
- **Field text**: matched against its lowercased form. Bonuses are computed
against the **original** text, because case is a signal (`camelCase`) that
lowercasing destroys.
- **Compact form** of a string: lowercase with whitespace removed. Used only
for the exact and prefix tests.
Lowercasing is per-character simple lowercase (`char::to_lowercase` /
`String.prototype.toLowerCase`). Positions are **character** positions —
Unicode scalar values in Rust, UTF-16 code units in TypeScript, which agree for
every character these fields realistically hold; ranges are returned in the
host language's own unit, since they exist to slice that language's string.
### What a match is
Case-insensitive **subsequence**: every character of the normalized query
appears in the lowercased field text, in order, not necessarily adjacent. A
field with no such embedding does not match.
### Word boundaries
A matched character at position `p` earns exactly one character bonus, taking
the first rule that applies:
| Rule | Bonus |
| --- | --- |
| `p == 0` — first character of the field | `+18` |
| The character before it is a **separator**: `/` `\` `-` `_` `.` `:` or a space | `+16` |
| It is uppercase and the character before it is lowercase (a camelCase hump) | `+12` |
| It is a digit and the character before it is not | `+12` |
| Otherwise | `0` |
That is one rule for both shapes the doc has to cover. In a **path**, `/` is a
separator, so the first character of every segment is a word start: `foo` in
`~/dev/foobar` starts a segment and outscores `foo` in `~/src/myfoo`, which
starts nothing. In a **session name**, `-`, `_`, `.` and spaces do the same
work, so `ws` reaches `web-search` more cheaply than `websearch`.
### Score
Let the query characters be matched at positions `p₀ < p₁ < … < pₘ₋₁`, and let
`p₋₁ = -1`. For each matched character `i`, with `gap = pᵢ - pᵢ₋₁ - 1`:
```
contribution(i) = 16 // every matched character
+ bonus(pᵢ) // the table above
+ (gap == 0 ? +8 // adjacent to the previous match
: -min(gap, 12))
```
`gap` for `i = 0` is the number of characters skipped before the first match, so
a match that starts late is penalised exactly like an internal gap, and the cap
is the same one.
The **field score** is the sum of the contributions, plus at most one whole-field
adjustment:
- compact field text **equals** the normalized query → `+64`
- else compact field text **starts with** the normalized query → `+32`
Length is deliberately not in the score — it is a tie-break, so a long field
never loses to a short one that matched worse.
### Which embedding
A query can sit in a field many ways. The one that counts is the
**highest-scoring** embedding; among embeddings that score the same, the
**leftmost** — compare position vectors element by element, smaller wins.
Greedy leftmost-first matching is not sufficient and must not be used: in
`maestro-tui`, `mtu` greedily takes `m₀ a₁ …` and never reaches `tui`. Both
implementations use the obvious dynamic program over
`(query index, text position)`, carrying the best score and its position
vector, since the gap term depends only on the previous matched position.
The whole-field adjustment is constant for a `(query, field)` pair, so adding it
after the dynamic program cannot change which embedding wins.
### Ordering
Sort by score, highest first. Equal scores break in this order:
1. **Kind** — `session`, then `command`, then `directory`.
2. **Length of the matched field text**, shorter first.
3. **The matched field text**, ascending, compared by code point, case
sensitive.
4. **Input order.** The sort is stable, so candidates the caller ordered
deliberately — sessions most recently focused first, commands in registry
order — keep that order when nothing else separates them.
Kind leads because that is the ruling the ambiguous cases need: a session named
`kill` and the `kill` command that score alike put the session first, because
the operator who typed a session's name meant the session.
### Empty query
A normalized query that is empty **matches every candidate**, each with score
`0` and no ranges, in input order. The bar's own rules decide what is in the
candidate list at that point (sessions only at the top level); the matcher does
not filter by kind.
## Fixtures
These are the contract. Both matchers are tested against exactly these cases;
the prose above is the explanation of why they come out this way.
Candidates are written as `kind(fields)`; unlisted fields are absent.
`session(name, dir, command, tool)`. Scores are shown for diagnosis — **the
order is what is being asserted**, and an implementation that ranks correctly
with different absolute numbers has still failed, because the numbers are how
the next fixture stays predictable.
### F1 — empty query keeps input order
```
query: ""
candidates: session("kill", "~/dev/api", "bash")
session("killer-app", "~/dev/killer-app", "claude --resume", "claude")
command("Kill selected session")
expected: session("kill") score 0
session("killer-app") score 0
command("Kill selected session") score 0
```
Every candidate matches, in the order given. No ranges.
### F2 — a session named `kill` against the `kill` command
```
query: "kill"
candidates: (as F1)
expected: session("kill") 178 name
session("killer-app") 146 name
command("Kill selected session") 146 label
```
`kill` wins on the exact bonus. The other two **tie at 146** — both are a
contiguous prefix match — and the kind tie-break puts the session first.
### F3 — a fragment matching mid-segment inside a path
```
query: "foo"
candidates: directory("~/dev/foobar")
directory("~/src/myfoo")
directory("~/foo")
expected: directory("~/foo") 78 ranges [2,3,4]
directory("~/dev/foobar") 74 ranges [6,7,8]
directory("~/src/myfoo") 56 ranges [8,9,10]
```
The first two start a path segment; the third is mid-segment and loses by the
whole boundary bonus. `~/foo` beats `~/dev/foobar` only because less was
skipped before the match.
### F4 — a query matching nothing
```
query: "zzz"
candidates: session("kill", "~/dev/api", "bash")
command("Kill selected session")
expected: (empty)
```
The matcher returns an empty list, never a list of zero-scored candidates. The
bar renders its no-results state.
### F5 — a non-contiguous subsequence
```
query: "mtu"
candidates: session("maestro-tui")
session("maestro-daemon")
session("mtui-scratch")
expected: session("mtui-scratch") 122 ranges [0,1,2]
session("maestro-tui") 91 ranges [0,8,9]
```
`maestro-daemon` has no `u` after its `t` and does not match. `maestro-tui`
does, across a gap — which greedy matching would miss entirely.
### F6 — a name beats a directory
```
query: "api"
candidates: session("api", "~/dev/web", "bash")
session("worker", "~/dev/api", "bash")
expected: session("api") 154 name
session("worker") 50 directory
```
The second session is found through its directory, and highlights there.
### F7 — case-insensitive, tie broken by length
```
query: "api"
candidates: session("API-Gateway")
session("apiary")
expected: session("apiary") 122 name
session("API-Gateway") 122 name
```
Both are prefix matches and score identically. Same kind, so length decides:
6 characters before 11. Input order does not save `API-Gateway`.
### F8 — the tool field
```
query: "claude"
candidates: session("nameless", "~/dev/x", "claude --resume", "claude")
session("clay", "~/dev/y", "bash")
expected: session("nameless") 186 tool
```
`clay` has no `claude` subsequence anywhere and drops out. `nameless` matches
its `tool` exactly (`+64`, weight `-40`, giving 186) which beats the prefix
match on its `command` field (`+32`, weight `-32`, giving 162).
### F9 — a word boundary inside a session name
```
query: "ws"
candidates: session("websearch")
session("web-search")
expected: session("web-search") 71 ranges [0,4]
session("websearch") 56 ranges [0,3]
```
The `s` after `-` earns the boundary bonus; the `s` inside `websearch` earns
nothing.
### F10 — command labels
```
query: "se"
candidates: command("Kill selected session")
command("Create a session")
command("Show help")
expected: command("Show help") 53 ranges [0,6]
command("Kill selected session") 51 ranges [5,6]
command("Create a session") 47 ranges [9,10]
```
`Show help` starts at position 0; the other two start at a word boundary but
later, and pay for the skipped characters.
### F11 — a query against session directories
```
query: "dev"
candidates: session("api", "~/dev/api", "bash")
session("notes", "~/documents/dev-notes", "nvim")
session("scratch", "~/srv/devops", "bash")
expected: session("api") 54 directory, ranges [2,3,4]
session("scratch") 50 directory, ranges [6,7,8]
session("notes") 44 directory, ranges [12,13,14]
```
All three start a path segment. They separate purely on how much was skipped
first, and `notes` hits the `-12` gap cap.
### F12 — exact beats prefix
```
query: "quit"
candidates: command("Quit Maestro")
command("Quit")
expected: command("Quit") 178 label
command("Quit Maestro") 146 label
```
The 32-point difference between the exact and prefix adjustments is the whole
gap; nothing else about the two matches differs.
docs/PREVIEW.md
+12 -8
View File
@@ -77,15 +77,19 @@ Nothing moves a second time on commit.
## Timing
A preview follows the highlight closely enough to be usable as a way to look
around, and lags a pointer enough not to flash rows crossed on the way
somewhere else.
**A preview is never delayed.** Landing on a row — by pointer or by `j`/`k` —
shows it on the next frame, and so does leaving every row. There is no
settling period in front of the first preview, because that period would sit
in front of the one preview the operator actually meant.
| Trigger | Delay |
|---|---|
| Keyboard step (`j`/`k`, arrows) | 60 ms |
| Pointer hover (web, mouse only — never touch) | 150 ms |
| Clearing (highlight left every session) | same delay as the trigger that set it |
What is bounded is how *often* the pane may swap: at most once per 120 ms.
A burst inside one window — `j` held down, or the pointer sweeping the length
of the sidebar — shows the row it started on, then the row it ended on, and
none of the rows in between. So a walk costs a couple of pane mounts rather
than one per row, without the operator ever waiting on one.
The highlight itself is not bounded by any of this: the row lights up on the
same frame as the input, whatever the pane behind it is doing.
Touch has no hover, and a tap already opens a session, so touch never previews.