# IDEA.md – your own graphical Subversion client for macOS This file is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build a client of your own. It is based on a project that exists and works, and everything below turned out to be true when it was built. ## 1. What to build A native macOS app for working with Subversion without the terminal, for someone who uses svn now and then and does not want to pay a recurring licence for a ready-made client. The model is SmartSVN: a project window with a directory tree, a file table and panels below. The app should be able to: - Show several working copies in **one** window. The sidebar lists them, each with its directory tree; the right side shows the selected one. - Show status: a file table with the local state (modified, added, deleted, unversioned, missing, conflicted), revision, author and date, and the number of changes per directory in the tree. - Show the changes in a selected file (diff against BASE) below the table. - Commit a selection, with checkboxes and a message. Unversioned files that are checked get added, missing ones get removed. - Run Update, Add, Revert, Delete and Rename, with an Output panel showing what svn answered, and a Stop button. - Show the log: revisions, changed paths, diff per path, search. - Browse a repository from a URL, create a folder there and check out, including straight into a folder on disk that already contains files. - Show what is waiting on the server without updating, on request and at an interval in the background. - Resolve conflicts: my version, their version, mark as resolved, or in a three-way editor where you choose a side chunk by chunk and can edit the result freely. - Refresh by itself when files change on disk. Not included: revision graph, annotate, merge, switch, branches and tags, change sets, properties, externals, locks, and support for platforms other than macOS. The three-way editor is for text files; tree conflicts and property conflicts are resolved without it. Login and certificate dialogs were not part of the first version either; see section 4. ## 2. Stack and architecture - **Swift with AppKit**, macOS 14 or later. An important choice. An SVN client is almost nothing but standard controls (tree, sortable table, split views, toolbar, menus), and AppKit has them ready with keyboard handling, accessibility and column memory. A cross-platform framework would have meant building all of it by hand. AppKit rather than SwiftUI: trees and tables with tens of thousands of rows are AppKit's home ground. - **Swift Package Manager, no Xcode project.** Two targets: a core without windows and an app. The bundle (`.app`) is assembled by a shell script: copy the binary, write `Info.plist`, sign ad hoc. Command Line Tools are enough. You can swap this for an Xcode project, but then the AI tool loses the ability to build and try things itself. - **The engine is the `svn` command with `--xml`**, not libsvn. `status`, `info`, `log` and `list` have stable XML output. libsvn is C with APR pools and would have cost a lot of bridging code. Put the engine behind a protocol (`SVNClient`) so it can be replaced later. Apple no longer ships svn; expect Homebrew's (`/opt/homebrew/bin/svn`) and look in PATH too. - **The core** runs processes, parses XML and diffs, builds the directory tree from the flat status list and holds the rules (what gets committed, when status is read again). Everything in the core is value types and is tested without a window. - **The app** has one window that owns the sidebar and the toolbar, and one controller per working copy that owns its state and its right-hand side. - No App Sandbox: the app has to start `svn` and read arbitrary folders. ## 3. Decisions that turned out to matter 1. **All contact with svn goes through a protocol in the core.** The app never starts `svn` itself and never parses its output. Every new command becomes a method, a parser and a test against a real repository. That is what makes bugs get found by tests and not by the user. 2. **Test against real repositories, not made-up XML.** Each test creates its own repository with `svnadmin create` in a temporary folder, checks out over `file://` and runs real commands. Nearly every pitfall in section 4 was found that way. 3. **The app must be reviewable without hands.** Build in environment variables that open a given working copy, select a folder or file, open a dialog, run a command, and save the window as a PNG and quit. The AI tool can then see its own interface. Draw the window's view to an image; do not capture the screen. 4. **One window, one controller per working copy.** The window owns the sidebar and the toolbar; the working copies own their state. Decide this from the start. Building one window per working copy and merging them later cost a rewrite. 5. **Exactly what is checked gets committed.** Run commit with `--depth empty` and list every target. Otherwise a checked folder drags along files that were unchecked. Put the rules in the core: add the unversioned, remove the missing, include the contents of a new folder, and include an added parent folder even if it was not checked. 6. **Remote status is fetched separately and kept.** `svn status -u` needs the network. Keep the answer and lay it over every local read, so an ordinary refresh never needs the network. Drop it after an update. 7. **Dangerous commands ask first, and nothing is deleted needlessly.** Revert and Delete are confirmed. Delete on an unversioned file moves it to the Trash. "Mark as resolved" warns if `<<<<<<<` is still in the file. 8. **In the three-way editor the result is an ordinary editable text.** Show my version and theirs read-only at the top and the result below. Work out the chunks with a line-by-line diff3 against the base: what changed on one side only merges by itself, and only what changed differently on both sides is a conflict. The window keeps track of how long each chunk is in the result text, so "use theirs" replaces the right lines even after the user has typed in the text. That is simpler and sturdier than locking the text into editable boxes per chunk. ## 4. Pitfalls - **Set `LC_ALL=en_US.UTF-8` for every svn run.** An app started from Finder has no `LANG` and runs in the C locale, where svn refuses paths with non-ASCII characters. You also get English error messages to recognise. - **Always run with `--non-interactive`.** Otherwise svn can sit waiting for an answer nobody can give. - **Read stdout and stderr at the same time.** Read one after the other and the second pipe fills up, and both svn and the app hang. - **`svn status --xml` does not say whether an entry is a file or a folder.** Ask the disk. For what is not on disk: treat the entry as a folder if some other entry lies below it. - **An added file has revision `-1` in the XML.** Show nothing, not -1. - **`@` in file names.** svn reads `@` in a target as the start of a revision. Append a trailing `@` to targets containing the character. But not everywhere: - `svn diff` on a path in the working copy reads no `@`; write the path as it is. - The destination of `svn move` is not parsed for `@`, only the source. - Neither is the destination folder of `svn checkout`. - In URLs, percent-encoding does not help: svn decodes `%40` first. Append a trailing `@` there too. Write a test with `@` in the name for every command. - **A name starting with `-`** is read as a flag. Write `./-name`. - **Pass targets through `--targets` and the message through `--file`.** A thousand files do not fit on a command line, and a message can contain anything. `svn update` does not take `--targets`, though. - **svn sleeps until the next whole second** after every command that changed the working copy. Each such command takes up to a second. Nothing can be done about it; allow for it in the test run time. - **`svn status` writes to `.svn`.** If you watch the folder to refresh automatically, every refresh triggers the next. Ignore changes that only touch `.svn` shortly after your own read, but not later: then someone ran svn in the terminal. - **Throttle the automatic refresh.** Wait at least three times as long as the last read took, and do not read at all while the app is in the background; read once when it comes to the front. - **The log should start at HEAD, not BASE.** Otherwise what was committed after the last update does not show. If the path no longer exists in HEAD, fall back to BASE. - **Fetch a revision's diff in one call** (`svn diff -c REV` against the repository root) and split it per file. Added, deleted and moved files are then treated alike. - **Check out straight into a folder with files using `--force`.** Without it, a local file with the same name as one in the repository becomes a tree conflict. With it, the file keeps its local content and shows up as modified. Nothing is overwritten. - **Do not guess the names of the conflict files.** svn puts three files next to a file in conflict (the base, mine and theirs). The paths are in `svn info --xml` as `prev-base-file`, `prev-wc-file` and `cur-base-file`. - **Split the text into lines that keep their line endings.** Each side can then be put back together character for character, even with CRLF and a last line without a newline. When two sides are placed one after the other and the first ends without a newline, one has to be added, or two lines grow together. - **Count chunk lengths in UTF-16**, as NSTextView does, and update them in `textView(_:shouldChangeTextIn:replacementString:)` before every change. A change can span several chunks: subtract what is removed from each one, and add the new text to the first. - **Clear the undo history when a chunk is replaced with a button.** Otherwise it points at positions in the text that are no longer right. - **Show an unresolved conflict with one side's lines, but mark it and ask on save.** An empty gap or conflict markers in the result are harder to work with, but without the question a conflict is saved as if resolved. - **Do not write the merged file atomically.** A new file loses the executable bit and other permissions the old one had. - **Toolbar buttons should target the window**, and the window forwards to the working copy on display. A button targeting a working copy keeps acting on it after another one is selected. - **A failed build leaves the old binary in place.** Check that the build succeeded before trusting a screenshot. - **Login and certificates.** With `--non-interactive`, svn fails instead of asking. The first version only works against a server where svn already has the password and certificate stored. Plan for a dialog that recognises the errors (E170001, E215004, E230001), asks, and runs the command again. ## 5. Requirements and measures Measured in the project, on a Mac with Apple Silicon, as benchmarks: - Reading status (info + status + building the tree): 0.17 s for 91 entries, 0.25 s for 905, 0.67 s for 5,488 and 1.49 s for 15,149. The floor of 0.17 s is two process launches. - Diff of one file: no noticeable wait (0.01 s for the svn call itself). - The finished dmg: 2.5 MB. - About 8,400 lines of Swift, tests included. - The three-way editor takes files up to 20,000 lines per side; above that it declines and says why. - Cut a diff at 50,000 lines. - The log is fetched a hundred revisions at a time. ## 6. How it is verified A step is done when all four hold: 1. The release build succeeds without warnings in your own code. 2. The tests pass. Against a real repository they should cover: status for every state, diff (modified, added, deleted, binary, properties), commit of a selection, update with a second working copy committing, revert, delete, rename, log in pages, listing, checkout, a new folder in the repository, remote status, conflicts (text and tree), merging a conflict from svn's three files, and cancellation. The merge is also tested on its own: changes on either side, conflicts, the same change on both sides, additions first and last, empty texts, and that each side can be reproduced exactly. Use file names with spaces, non-ASCII characters and `@`. 3. The bundle builds and is signed. 4. The interface has been reviewed in a screenshot taken by the app itself. Commands that change anything are only tried against repositories the test or the trial run created itself, never against real working copies. What can only be judged with a mouse and eyes, and everything against a real server, is tried by a person. ## 7. Way of working - **Plan first.** Let the tool study the model, propose a language and an engine with reasons, and write a plan before any code is written. - **One ticket per feature**, in an issue tracker or a plain list: what the user should be able to do, where in the interface, and what is not included. Build one at a time, in order: status, diff, commit, commands, log, repository browser, incoming, conflicts, automatic refresh, icon, three-way editor. - **Write down what was measured** when a ticket is closed, and what could not be tried. - **Keep the reasoning in the repository**: a `docs/research.md` with the trade-offs and what turned out wrong, and an instruction file for the tool with the architecture, the verification chain and the rules. - **Ask about real decisions**, not about things with a sensible default. ## 8. The prompt ``` I want to build a graphical client for Subversion for macOS. Read IDEA.md, which I am attaching, in full before you do anything: it describes what to build, which decisions matter and which pitfalls exist. Start in plan mode. Study how [SmartSVN or another model] is put together, check what is installed on my machine (svn, Swift, Xcode or only Command Line Tools) and propose a plan. Follow the stack in IDEA.md unless you find a reason to deviate; if so, say why. The app should be called [name] and have the bundle id [e.g. com.example.Name]. The interface should be in [English], comments and documentation in [English]. Split the work into tickets as in section 7 and keep them in [an issue tracker or a file TODO.md]. Build one ticket at a time. A ticket is done only when the verification in section 6 has been carried out; then write down what you measured and what you could not try. Never run commands that change anything against my real working copies in [folder]. Create your own test repositories with svnadmin create. Do not commit anything for me. Build in the screenshot hook from section 3 in the very first ticket, and review every interface change in a screenshot before you say it is done. ```