Lutra/docs/alpha-checklist.md
danny 33a7185d75
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run
F1: cosmetics: regex error reason, one date format, Close Tab
- Find shows a bad regex as "invalid pattern: unclosed group": the search
  crate keeps only the parser's reason, the UI drops the invalid-params
  prefix (userMessage).
- Dates read YYYY-MM-DD / YYYY-MM-DD HH:mm in local time everywhere
  (i18n formatDate/formatDateTime): Log, stash list, blame, recovery.
- buffer.close is "Close Tab" in the palette as in the menu; an engine test
  keeps palette labels starting with their menu item's wording.
- Docs: architecture, install (Jump List), localization parity, checklist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 19:31:43 +01:00

22 KiB
Raw Blame History

Alpha acceptance checklist

Status: C7 A2, written against main da58c83 (M0–M4) · Last updated: 2026-11-02

The alpha gate (roadmap.md › Alpha gate) asks for six workflows to work end to end. This checklist turns them into steps you do by hand, once on Windows and once on macOS. Each step names the action, then what you should see. Plan on 30–45 minutes per platform.

Everything runs offline against a demo project made by cargo xtask demo-project, with one exception: the first time Lutra opens a PHP project on a machine, it downloads Phpactor (about 4 MB). Do that once while you're online (step 0.4).

Ticking: each row has a [ ] for Windows and one for macOS. Write x for a pass, or the step number in your failure report for a fail.

Keys: Mod is Ctrl on Windows and Cmd on macOS. Alt is Option on macOS. Every command is also in the menu (☰ top left, or Alt+M) and in the palette (Mod+Shift+P), so if a shortcut does nothing, try the menu before you call it a failure, and note both results.

0. Before you start (about 5 min)

DEMO means the folder you create here: C:\lutra-demo on Windows, ~/lutra-demo on macOS. On Windows, keep the path short: git fails on paths near 260 characters.

# Action Expected Win Mac
0.1 Windows: use the installed Lutra (Test) (check that %LOCALAPPDATA%\Programs\Lutra Test\version.txt names the commit you want to test). macOS: build Lutra as macos.md describes. Lutra starts and shows an empty window with the otter slogan. Quit it again (Mod+Q). [ ] [ ]
0.2 Make lutra callable in your shell. Windows PowerShell: Set-Alias lutra "$env:LOCALAPPDATA\Programs\Lutra Test\lutra.exe". macOS: alias lutra=<repo>/target/release/lutra (the folder your build wrote to). lutra --help prints the usage. [ ] [ ]
0.3 In the repository: cargo xtask demo-project C:\lutra-demo (Windows) or cargo xtask demo-project ~/lutra-demo (macOS). It prints demo-project: ready and two paths: DEMO/shop (the project) and DEMO/origin.git (its "remote"). [ ] [ ]
0.4 Online: start Lutra, File › Open Folder… (Mod+O), choose DEMO/shop. The tree shows public, src, var (greyed: ignored by Git), .gitignore, composer.json, README.md. The status bar shows main bottom right. The first time on this machine, toasts say the Phpactor download started and finished. [ ] [ ]

PHP 8.2 or newer must be installed (php -v). Without it, steps 3.x fail with a "PHP not found" warning; that's a setup problem, not a Lutra failure.

1. Project, editor, save, recovery (about 10 min)

# Action Expected Win Mac
1.1 Expand src › Service in the tree, click Checkout.php, then PriceCalculator.php. Each opens in a tab with PHP highlighting; the second tab is active. Clicking the first tab switches back. [ ] [ ]
1.2 Mod+1 twice. The project tree hides and comes back. [ ] [ ]
1.3 In README.md, add a line Edited by hand. and press Mod+S. A dot marks the tab as modified while you type; it disappears on save. The tab and the tree entry turn the "modified" colour, and a coloured bar appears in the narrow gutter beside the new line. [ ] [ ]
1.4 Type another line in README.md, then press Mod+W at once. A question offers Save / Don't Save / Cancel. Cancel keeps the tab; Save closes it and keeps the text. [ ] [ ]
1.5 In README.md, add a space at the end of the new line, then click another tab. The first tab's modified dot goes away (autosave on tab switch). [ ] [ ]
1.6 Palette: Mod+Shift+P, type save all, Enter. The palette lists "Save All" with its shortcut, runs it and closes. Arrow keys move, Escape closes. [ ] [ ]
1.7 ☰ (top left) or Alt+M. A menu with groups File, Edit, View, Go, Git, Navigate, Refactor, Tools, Help. Arrow keys move, Escape closes. [ ] [ ]
1.8 Settings: Mod+,. Type font in the search field, set "Editor font size" to 18. The editor text grows at once; there's no OK button. "Reset to default" sets it back to 14. [ ] [ ]
1.9 Settings › Appearance › Theme: Light, then Dark, then System. The whole window, editor and terminal switch at once, with no reload; System follows the OS setting. [ ] [ ]
1.10 Settings › PHP: look at "PHP executable" and "Phpactor PHAR"; Settings › Git: "Git executable". Each is a text field with "Browse…"; while empty it says "Detected automatically". "Browse…" opens the native file picker; Cancel there changes nothing. [ ] [ ]
1.11 In "PHP executable", type a path with a space at the start, such as php, and press Enter. It is refused under the field with a message about spaces; the stored value doesn't change. Escape closes the dialog. [ ] [ ]
1.12 Crash recovery, preparation. Settings › Editor: turn off "Autosave when leaving the window" and set "Autosave after idle (seconds)" to 0. Both apply at once. [ ] [ ]
1.13 Type Unsaved line into composer.json without saving, wait 3 seconds, then kill Lutra hard. Windows: taskkill /F /IM lutra-desktop.exe. macOS: pkill -9 lutra-desktop. (This ends every running Lutra.) The window disappears at once, without a question. [ ] [ ]
1.14 Start Lutra again and open DEMO/shop. A dialog "Unsaved changes found" lists composer.json. "Restore All" opens it as a modified tab with Unsaved line in it. [ ] [ ]
1.15 Remove the text Unsaved line (leave the line break after the closing }), save. In Settings › Editor, reset both autosave settings to their defaults. composer.json is no longer modified (no colour in the tree). [ ] [ ]

2. Navigation (about 5 min)

# Action Expected Win Mac
2.1 Go to File: Mod+P, type pricecalc. src/Service/PriceCalculator.php is the first row, with the matched letters marked. Enter opens it. [ ] [ ]
2.2 Go to Class: Mod+Alt+C, type repo. ProductRepository (interface) and InMemoryProductRepository, with their namespace. Tab switches between the File, Class and Symbol modes and keeps the text. [ ] [ ]
2.3 Go to Symbol: Mod+T, type Checkout::total, Enter. Checkout.php opens with the cursor on total. Typing format instead lists the function format_price. [ ] [ ]
2.4 Structure: with Checkout.php active, Mod+2. A tree: the namespace Demo\Shop\Service, under it Checkout with __construct, $products, $calculator, total, preview. Clicking preview puts the cursor on it. Mod+2 again hides it. [ ] [ ]
2.5 Find in Files: Mod+Alt+F, type VAT_RATE, Enter. The Find tab at the bottom: 2 matches in 1 file, each with line number and the match marked. Enter or a click on a match opens the file there. [ ] [ ]
2.6 Search for ignored by. "No matches": the log file in the ignored var/ folder isn't searched. [ ] [ ]
2.7 Turn on Regex and search gross\w*\(. Matches in PriceCalculator.php and Checkout.php. An invalid regex such as ( shows an error under the field, not a toast. [ ] [ ]

3. Code assistance (about 7 min)

Wait until the language server is ready: the status bar shows indexing progress for a few seconds after opening the project.

# Action Expected Win Mac
3.1 Open src/Service/Checkout.php. Within a few seconds grossPrice on line 51 gets a red wavy underline (the demo's deliberate error). Hovering it shows Method "grossPrice" does not exist on class "Demo\Shop\Service\PriceCalculator". [ ] [ ]
3.2 Problems: Mod+Alt+P. The Problems tab lists that error under Checkout.php, with line 51. Enter or a click jumps to it. [ ] [ ]
3.3 Change grossPrice to gross on line 51. The underline and the Problems entry disappear within a few seconds. [ ] [ ]
3.4 On line 42, delete the ; after format_price($sum) and save. An error is reported on line 43, the } after the missing ; (on Windows from php -l, after the save). Put the ; back and save; it goes away. [ ] [ ]
3.5 Completion: on a new line in preview(), type $this->calculator->. A list opens with gross and grossFor, with kind icons. Enter inserts the chosen one. Ctrl+Space opens the list on demand. Undo the line. [ ] [ ]
3.6 Hover: rest the mouse on PriceCalculator in the constructor. Then put the cursor on it and press Mod+I. A tooltip with the class's doc comment, "Turns net prices into gross prices.", both ways. [ ] [ ]
3.7 Signature help: on a new line in preview(), type round(1.5, (the editor adds the )). A tooltip shows round(int|float $num, int $precision = 0, int $mode = NULL): float with $precision marked. (Phpactor shows none for namespaced functions such as format_price; that is not a Lutra failure.) Escape closes it; Mod+Shift+Space brings it back. Undo the line. [ ] [ ]
3.8 Definition: cursor on findBySku (line 33), F12. Then Mod+click on PriceCalculator in the constructor. The first opens ProductRepository.php (or a picker that includes it) at findBySku; the second opens PriceCalculator.php. [ ] [ ]
3.9 References: in src/Model/Product.php, cursor on the class name Product, Shift+F12. A References tab lists the uses in ProductRepository.php, InMemoryProductRepository.php, PriceCalculator.php and public/index.php, each with its line, plus the class itself in Product.php. A click opens the use. [ ] [ ]
3.10 Rename: in ProductRepository.php, cursor on findBySku, F2, type findProduct, Enter. A field shows "Changes N uses in M files" before you confirm. Afterwards a toast reports the rename; the interface, InMemoryProductRepository.php and Checkout.php all say findProduct, and no new error appears in Problems. Keep the change (it is committed in 5.4). [ ] [ ]

4. Terminal (about 3 min)

# Action Expected Win Mac
4.1 Mod+Shift+T. A Terminal tab "Local" opens at the bottom with your shell (PowerShell on Windows, your login shell on macOS) in DEMO/shop, focused. [ ] [ ]
4.2 Run php public/index.php. It prints 19.88 EUR. [ ] [ ]
4.3 Run git log --oneline -3. The three newest commits, in colour. [ ] [ ]
4.4 Windows: ping -t 127.0.0.1; macOS: ping 127.0.0.1. Then Ctrl+C. Ping runs until Ctrl+C stops it (the key goes to the shell, not to Lutra). [ ] [ ]
4.5 Select some output, Mod+Shift+C, then paste into the editor. The selected text is pasted. [ ] [ ]
4.6 The + button in the Terminal tab; then close "Local (2)" with its ×. A second terminal "Local (2)" starts; closing it leaves "Local". [ ] [ ]
4.7 Switch between the Find, Problems and Terminal tabs; the terminal keeps its screen. Then switch theme (1.9) once. The terminal output is still there and takes the new colours. [ ] [ ]

5. Git (about 15 min)

Before this section: DEMO/shop has the changes from 1.3, 3.3 and 3.10. The demo's origin holds one commit ("Start a changelog") that shop hasn't fetched yet; the branch feature/discounts conflicts with main in PriceCalculator.php.

# Action Expected Win Mac
5.1 In the terminal: echo note > notes.txt. notes.txt appears in the tree in the "untracked" colour. [ ] [ ]
5.2 Open README.md, Git › Show Diff (Mod+Alt+Shift+D). Then Git › Next Change (Alt+Shift+]) and Previous Change (Alt+Shift+[). A "Diff: README.md" tab shows the staged version left (the committed one, since nothing is staged) and your copy right, with the new lines highlighted. Next/Previous move the cursor between changed chunks, wrapping. Typing on the right edits the file. [ ] [ ]
5.3 Changes: Mod+Alt+Shift+G. The Changes tab: Changes with Checkout.php, InMemoryProductRepository.php, ProductRepository.php, README.md; Untracked with notes.txt. Double-click on a file opens its diff. [ ] [ ]
5.4 Tick the checkbox of the Changes group (or select a row and press Space), leave notes.txt untracked. Mod+Alt+Shift+M, type Rename findBySku and fix the preview, Mod+Enter. The files move to Staged, then the commit runs; a toast says "Committed : Rename findBySku…". The gutter bars and file colours go away; only notes.txt is left. [ ] [ ]
5.4b In the Changes tab, right-click notes.txt › Add to .gitignore. A toast "Added to .gitignore: notes.txt"; notes.txt leaves Untracked and turns the ignored colour in the tree; .gitignore shows as changed. [ ] [ ]
5.5 Amend: tick .gitignore in Changes (so the amend takes it along), then tick "Amend" with an empty message box. Edit the text to Rename findBySku to findProduct and fix the preview, Commit. The box fills with the last commit's message when you tick Amend. The commit is replaced (the log in 5.6 shows only the new text). [ ] [ ]
5.6 Git › Log. The Log tab draws a graph: feature/customer branching off and merged back, feature/discounts branching off, badges for HEAD, main, origin/main, v0.1.0, origin/release/1.0. Authors Ada Lindqvist, Ben Okafor, Cleo Marchetti, dated 2024–2026, and "Lutra Tester" (the demo's Git user) on your own commits. Selecting a commit shows its message and files on the right; double-clicking a file opens its diff at that commit (read-only). [ ] [ ]
5.7 Type price in the message filter; then clear it. Only commits whose message contains "price" are listed (without a graph), then all again. [ ] [ ]
5.8 Right-click src/Service/PriceCalculator.php in the tree › Show History. The Log shows "History of src/Service/PriceCalculator.php": "Round gross prices to cents" and "Add price calculator and price formatting". The chip's × clears it. [ ] [ ]
5.9 Open PriceCalculator.php, Git › Annotate with Git Blame. A gutter with date and author per run of lines: Ben Okafor (2026-08-14) on the round(...) line and the "rounded to cents" doc line, Cleo Marchetti (2025-06-02) on most others; newer lines have a stronger bar. Hovering an annotation shows the commit; a click selects it in the Log. Running the command again hides the gutter. [ ] [ ]
5.10 Git › Fetch. A toast says the fetch is done; the status bar shows ↑1 ↓1 (your commit, the changelog commit). [ ] [ ]
5.11 Git › Pull. A toast says the pull is done; CHANGELOG.md appears in the tree; the status bar shows ↑2 (your commit and the merge of the pull). [ ] [ ]
5.12 Git › Push. A toast says the push is done; the arrows disappear. In the terminal, git --git-dir ../origin.git log --oneline -1 shows the pull's merge commit. [ ] [ ]
5.13 Click main in the status bar. The branch popup: Local feature/customer, feature/discounts, main (checked, "current"); Remote origin/main, origin/release/1.0. Typing filters. [ ] [ ]
5.14 Choose origin/release/1.0. A toast; the status bar says release/1.0; CHANGELOG.md and public/ vanish from the tree; open tabs of changed files reload. [ ] [ ]
5.15 Git › New Branch…, name try/scratch, "Check out" on, Create. Then switch back to main with the popup. The status bar shows try/scratch, then main again, with CHANGELOG.md back. [ ] [ ]
5.16 Change a line in src/Model/Product.php, save. Git › Stash Changes…, message wip product, Stash. A toast; Product.php is back to its committed text (an open tab reloads). [ ] [ ]
5.17 Git › Stashes… stash@{0} "wip product" on main with its date. Pop brings the change back and removes the entry. Then undo the change in Product.php and save. [ ] [ ]
5.18 Git › Merge…, choose feature/discounts. A toast reports conflicts; a list shows src/Service/PriceCalculator.php as conflicted; src/Service/DiscountPolicy.php appears in the tree. [ ] [ ]
5.19 Git › Abort Merge…, confirm. The merge is undone: DiscountPolicy.php is gone, no conflict colour, main as before. [ ] [ ]
5.20 Git › Merge… feature/discounts again, then "Resolve…" on PriceCalculator.php. Three editors: current branch (left), result (middle), merged branch (right), "1 of 1 conflicts open" (or more). [ ] [ ]
5.21 "Accept all left". Then, in the middle editor, change gross(float $net) to gross(float $net, float $discount = 0.0) and round($net * to round(max(0.0, $net - $discount) *. "Apply and mark resolved". Apply is enabled once no chunk is open; afterwards the file is saved and the list says no conflicts are left, offering "Commit…". [ ] [ ]
5.22 "Commit…". Keep the prefilled message, Commit. (The conflict warning from 5.18 closes by itself once no conflict is left, and toasts never cover the commit box.) Then php public/index.php in the terminal. The message box already holds Merge branch 'feature/discounts' (git's prepared message). The commit succeeds; the Log shows the merge with two parents; the script still prints 19.88 EUR. [ ] [ ]
5.23 Git › Manage Remotes… Add a remote backup with the URL of DEMO/origin.git; then Remove it (confirm in the row). origin is listed with its URL; backup appears and disappears again. [ ] [ ]
5.24 Git › Clone Repository…, URL DEMO/origin.git (the full path), "Browse…" and choose DEMO. The folder field becomes DEMO/origin. Clone shows progress, then the clone opens as the project (tree with src, public, CHANGELOG.md; branch main). [ ] [ ]
5.25 File › Open Folder… DEMO/shop. The demo project is back, with the Git state from 5.22. [ ] [ ]

6. CLI, control channel, MCP (about 5 min)

Lutra runs normally (started from its icon or the start menu), with DEMO/shop open.

# Action Expected Win Mac
6.1 In a terminal outside Lutra: lutra C:\lutra-demo\shop\src\Service\Checkout.php:30 (macOS: lutra ~/lutra-demo/shop/src/Service/Checkout.php:30). Lutra comes to the front with Checkout.php open and the cursor on line 30, centred. The command exits at once. [ ] [ ]
6.2 lutra --wait DEMO/shop/README.md (the real path, as in 6.1). The command waits. Close the README.md tab in Lutra (Mod+W); the command returns. Exit code 0 ($LASTEXITCODE in PowerShell, echo $? on macOS). [ ] [ ]
6.3 lutra DEMO/origin.git/HEAD (a file outside the project). Refused with "… is outside the project", exit code 1. [ ] [ ]
6.4 Quit Lutra. lutra DEMO/shop. Lutra starts by itself with the demo project. [ ] [ ]
6.5 MCP. With Lutra still running, run the block below for your platform in a terminal outside Lutra. Two JSON lines come back: the first with "serverInfo", the second with "isError":false. In Lutra the Go to File popup opens with checkout typed. [ ] [ ]
6.6 Control channel. Quit Lutra. Start it with a control port: Windows & "$env:LOCALAPPDATA\Programs\Lutra Test\lutra-desktop.exe" --control 7979 C:\lutra-demo\shop; macOS <repo>/target/release/lutra-desktop --control 7979 ~/lutra-demo/shop. Then send a request with the block below. A line {"id":1,"result":{"pong":true,...}}, then the palette opens in Lutra. Quit this instance afterwards: it uses its own data folder, so it doesn't show your normal settings. [ ] [ ]
6.7 Optional, if Claude Code is installed: claude mcp add lutra -- lutra mcp, then ask Claude "which files are open in Lutra?". Claude lists the open tabs through Lutra's MCP tools. [ ] [ ]

MCP check (6.5), Windows PowerShell:

'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"checklist","version":"1"}}}',
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_command","arguments":{"command":"goto.fileOpen","params":{"query":"checkout"}}}}' | lutra mcp

macOS:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"checklist","version":"1"}}}' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_command","arguments":{"command":"goto.fileOpen","params":{"query":"checkout"}}}}' | lutra mcp

Control channel (6.6), Windows PowerShell:

$c = New-Object System.Net.Sockets.TcpClient('127.0.0.1', 7979)
$w = New-Object System.IO.StreamWriter($c.GetStream()); $r = New-Object System.IO.StreamReader($c.GetStream())
$w.WriteLine('{"id":1,"method":"app.ping","params":{}}'); $w.Flush(); $r.ReadLine()
$w.WriteLine('{"id":2,"method":"engine.execute","params":{"command":"palette.open"}}'); $w.Flush(); $r.ReadLine()
$c.Close()

macOS:

printf '%s\n' '{"id":1,"method":"app.ping","params":{}}' '{"id":2,"method":"engine.execute","params":{"command":"palette.open"}}' | nc -w 2 127.0.0.1 7979

Reporting a failure

Don't fix or retry around it; write it down and carry on with the next step that doesn't depend on it. One note per failure, in the PM chat (Larissa), like this:

Step 5.11 · macOS 15.1 (M2) · build <commit from version.txt or `git rev-parse --short HEAD`>
Did: Git › Pull
Expected: toast, CHANGELOG.md in the tree, ↑2
Got: error toast "…" (exact text), no CHANGELOG.md
Repeatable: yes / once / not tried
Attached: screenshot

Useful extras when you have them:

  • a screenshot of the whole window;
  • for language-server steps (3.x): whether Tools › Restart PHP Language Server makes it work;
  • for Git steps: git status and git log --oneline --graph -5 from the terminal;
  • a crash: the terminal output if you started Lutra from a terminal.

When everything is ticked on both platforms, say so in the chat with the build commit; the PM records the alpha gate.

Revision history

Date Change Summary
2026-10-31 new A2: the six alpha workflows as manual steps, the demo project (cargo xtask demo-project), failure reports
2026-11-02 fix C9 F1: 5.22 no longer asks to close the conflict warnings
2026-11-01 dry run C8 C1: corrected after a Windows dry run (release build, control channel, CLI, MCP): 1.15 line break, 2.4 namespace node, 3.4 line 43, 3.7 round instead of format_price, 3.9 declaration, 5.2 staged label, 5.5 amend takes .gitignore along (else 5.16 stashes it), 5.6 own commits' author, 5.9 doc line, 5.13 no upstream next to "current", 5.22 sticky conflict toasts