# IDEA.md – en egen grafisk Subversion-klient för macOS Den här filen är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen klient. Den bygger på ett projekt som finns och fungerar, och allt nedan är sådant som visade sig stämma när det byggdes. ## 1. Vad som ska byggas En inbyggd macOS-app för att arbeta med Subversion utan terminalen, för den som använder svn ibland och inte vill betala en återkommande licens för en färdig klient. Förebilden är SmartSVN: ett projektfönster med katalogträd, filtabell och paneler under. Appen ska kunna: - Visa flera arbetskopior i **ett** fönster. Vänsterspalten listar dem, var och en med sitt katalogträd; högersidan visar den som är vald. - Visa status: filtabell med lokalt tillstånd (modified, added, deleted, unversioned, missing, conflicted), revision, författare och datum, och antalet ändringar per katalog i trädet. - Visa ändringarna i en markerad fil (diff mot BASE) under tabellen. - Checka in ett urval, med kryssrutor och meddelande. Okända filer som kryssas i läggs till, saknade tas bort. - Köra Update, Add, Revert, Delete och Rename, med en Output-panel som visar vad svn svarade, och en Stop-knapp. - Visa loggen: revisioner, ändrade sökvägar, diff per sökväg, sökning. - Bläddra i ett repo utifrån en URL, skapa en katalog där och checka ut, även rakt in i en katalog på disk som redan innehåller filer. - Visa vad som väntar på servern utan att uppdatera, på begäran och med ett intervall i bakgrunden. - Lösa konflikter: min version, deras version, markera som löst, eller i en trevägseditor där man väljer sida stycke för stycke och kan redigera resultatet fritt. - Läsa om av sig själv när filer ändras på disk. Ingår inte: revisionsgraf, annotate, merge, switch, grenar och taggar, change sets, properties, externals, lås, och stöd för andra plattformar än macOS. Trevägseditorn gäller textfiler; trädkonflikter och konflikter i egenskaper löses utan den. Inloggnings- och certifikatdialoger ingick inte heller i första versionen; se avsnitt 4. ## 2. Stack och arkitektur - **Swift med AppKit**, macOS 14 eller senare. Viktigt val. En SVN-klient är nästan bara standardkontroller (träd, sorterbar tabell, delade vyer, verktygsrad, menyer), och AppKit har dem färdiga med tangentbord, hjälpmedel och kolumnminne. Ett plattformsoberoende ramverk hade krävt att allt byggdes för hand. AppKit hellre än SwiftUI: träd och tabeller med tiotusentals rader är AppKits hemmaplan. - **Swift Package Manager, inget Xcode-projekt.** Två mål: en kärna utan fönster och en app. Bunten (`.app`) sätts ihop av ett skalskript: kopiera binären, skriv `Info.plist`, signera ad hoc. Det räcker med Command Line Tools. Går att byta mot ett Xcode-projekt, men då förlorar AI-verktyget möjligheten att bygga och prova själv. - **Motorn är kommandot `svn` med `--xml`**, inte libsvn. `status`, `info`, `log` och `list` har stabil XML-utdata. libsvn är C med APR-pooler och hade kostat mycket bryggkod. Lägg motorn bakom ett protokoll (`SVNClient`), så att den går att byta senare. Apple skickar inte längre med svn; räkna med Homebrews (`/opt/homebrew/bin/svn`) och leta även i PATH. - **Kärnan** kör processer, tolkar XML och diffar, bygger katalogträdet ur den platta statuslistan och innehåller reglerna (vad som checkas in, när status läses om). Allt i kärnan är värdetyper och testas utan fönster. - **Appen** har ett fönster som äger vänsterspalten och verktygsraden, och en styrning per arbetskopia som äger sitt tillstånd och sin högersida. - Ingen App Sandbox: appen måste få starta `svn` och läsa godtyckliga kataloger. ## 3. Beslut som visade sig avgörande 1. **All kontakt med svn går genom ett protokoll i kärnan.** Appen startar aldrig `svn` själv och tolkar aldrig dess utdata. Varje nytt kommando blir en metod, en tolk och ett test mot ett riktigt repo. Det är det som gör att fel hittas av tester och inte av användaren. 2. **Testa mot riktiga repon, inte mot påhittad XML.** Varje test skapar ett eget repo med `svnadmin create` i en tillfällig katalog, checkar ut via `file://` och kör riktiga kommandon. Nästan alla fallgropar i avsnitt 4 hittades så. 3. **Appen ska gå att granska utan händer.** Bygg in miljövariabler som öppnar en viss arbetskopia, väljer en katalog eller fil, öppnar en dialog, kör ett kommando, och sparar fönstret som PNG och avslutar. AI-verktyget kan då se sitt eget gränssnitt. Rita fönstrets vy till en bild; fånga inte skärmen. 4. **Ett fönster, en styrning per arbetskopia.** Fönstret äger spalten och verktygsraden; arbetskopiorna äger sitt tillstånd. Bestäm det från början. Att bygga ett fönster per arbetskopia och sedan slå ihop dem kostade en omskrivning. 5. **Exakt det ikryssade checkas in.** Kör commit med `--depth empty` och räkna upp varje mål. Annars drar en ikryssad katalog med sig filer som kryssats ur. Lägg reglerna i kärnan: lägg till okända, ta bort saknade, ta med innehållet i en ny katalog, och ta med en tillagd föräldrakatalog även om den inte kryssats i. 6. **Fjärrtillståndet hämtas för sig och sparas.** `svn status -u` kräver nät. Spara svaret och lägg det på varje lokal läsning, så att en vanlig omläsning aldrig kräver nät. Kasta det efter en update. 7. **Farliga kommandon frågar först, och inget tas bort i onödan.** Revert och Delete bekräftas. Delete på en okänd fil flyttar den till papperskorgen. "Markera som löst" varnar om `<<<<<<<` står kvar i filen. 8. **I trevägseditorn är resultatet en vanlig redigerbar text.** Visa min och deras version skrivskyddade överst och resultatet under. Räkna ut styckena med diff3 rad för rad mot basen: det som bara ändrats på ena sidan sammanfogas av sig självt, och bara det som ändrats olika på båda håll är en krock. Fönstret håller reda på hur långt varje stycke är i resultattexten, så att "använd deras" byter rätt rader även efter att användaren skrivit i texten. Det är enklare och tåligare än att låsa texten i redigerbara rutor per stycke. ## 4. Fallgropar - **Sätt `LC_ALL=en_US.UTF-8` för varje svn-körning.** En app startad från Finder har ingen `LANG` och kör i C-locale, där svn vägrar sökvägar med å, ä och ö. Du får också engelska felmeddelanden att känna igen. - **Kör alltid med `--non-interactive`.** Annars kan svn stå och vänta på ett svar ingen kan ge. - **Läs stdout och stderr samtidigt.** Läses de i tur och ordning och det andra röret fylls, hänger sig både svn och appen. - **`svn status --xml` säger inte om en post är fil eller katalog.** Fråga disken. För det som inte finns på disk: räkna posten som katalog om någon annan post ligger under den. - **En tillagd fil har revision `-1` i XML.** Visa tomt, inte -1. - **`@` i filnamn.** svn läser `@` i ett mål som början på en revision. Lägg till ett avslutande `@` på mål som innehåller tecknet. Men inte överallt: - `svn diff` på en sökväg i arbetskopian läser inget `@`; skriv sökvägen som den står. - Målet för `svn move` läses inte efter `@`, bara källan. - Målkatalogen för `svn checkout` läses inte heller. - I URL:er hjälper inte procentkodning: svn avkodar `%40` först. Lägg till ett avslutande `@` även där. Skriv ett test med `@` i namnet för varje kommando. - **Ett namn som börjar med `-`** läses som en flagga. Skriv `./-namn`. - **Skicka mål via `--targets` och meddelandet via `--file`.** Tusen filer får inte plats på en kommandorad, och ett meddelande kan innehålla vad som helst. `svn update` tar dock inte `--targets`. - **svn sover till nästa hela sekund** efter varje kommando som ändrat arbetskopian. Varje sådant kommando tar upp till en sekund. Det går inte att göra något åt; räkna med det i testernas körtid. - **`svn status` skriver i `.svn`.** Bevakar du katalogen för att läsa om automatiskt utlöser varje omläsning nästa. Ignorera ändringar som bara rör `.svn` strax efter en egen läsning, men inte senare: då är det någon som kört svn i terminalen. - **Stryp den automatiska omläsningen.** Vänta minst tre gånger så länge som förra läsningen tog, och läs inte alls medan appen ligger i bakgrunden; läs en gång när den kommer fram. - **Loggen ska börja i HEAD, inte i BASE.** Annars syns inte det som checkats in efter senaste update. Finns sökvägen inte kvar i HEAD, falla tillbaka på BASE. - **Hämta en revisions diff i ett anrop** (`svn diff -c REV` mot repots rot) och dela den per fil. Då behandlas tillagda, borttagna och flyttade filer lika. - **Checka ut rakt in i en katalog med filer med `--force`.** Utan den blir en lokal fil med samma namn som en i repot en trädkonflikt. Med den behåller filen sitt lokala innehåll och visas som ändrad. Inget skrivs över. - **Gissa inte namnen på konfliktfilerna.** svn lägger tre filer bredvid en fil i konflikt (basen, min och deras). Sökvägarna står i `svn info --xml` som `prev-base-file`, `prev-wc-file` och `cur-base-file`. - **Dela texten i rader som behåller sina radslut.** Då går varje sida att sätta ihop igen tecken för tecken, även med CRLF och en sista rad utan nyrad. Läggs två sidor efter varandra och den första slutar utan nyrad måste en läggas till, annars växer två rader ihop. - **Räkna stycklängder i UTF-16**, som NSTextView gör, och uppdatera dem i `textView(_:shouldChangeTextIn:replacementString:)` före varje ändring. En ändring kan sträcka sig över flera stycken: dra bort det som tas bort ur vart och ett, och lägg det nya på det första. - **Töm ångra-historiken när ett stycke byts ut med en knapp.** Den pekar annars på lägen i texten som inte längre stämmer. - **Visa en olöst krock med ena sidans rader, men markera den och fråga vid spara.** En tom lucka eller konfliktmarkörer i resultatet är svårare att arbeta med, men utan frågan sparas en krock som om den vore löst. - **Skriv inte den sammanfogade filen atomärt.** En ny fil tappar körbarhetsbiten och andra rättigheter som den gamla hade. - **Verktygsradens knappar ska ha fönstret som mål**, och fönstret skickar vidare till arbetskopian som visas. En knapp med en arbetskopia som mål fortsätter gälla den efter att en annan valts. - **Ett misslyckat bygge lämnar den gamla binären kvar.** Kontrollera att bygget gick igenom innan du litar på en skärmbild. - **Inloggning och certifikat.** Med `--non-interactive` misslyckas svn i stället för att fråga. Första versionen fungerar bara mot en server där svn redan har lösenord och certifikat sparade. Planera för en dialog som känner igen felen (E170001, E215004, E230001), frågar och kör om kommandot. ## 5. Krav och mått Uppmätt i projektet, på en Mac med Apple Silicon, som riktmärken: - Läsa status (info + status + trädbygge): 0,17 s för 91 poster, 0,25 s för 905, 0,67 s för 5 488 och 1,49 s för 15 149. Golvet på 0,17 s är två processtarter. - Diff av en fil: omärkbar väntan (0,01 s för själva svn-anropet). - Den färdiga dmg:n: 2,5 MB. - Ungefär 8 400 rader Swift, tester inräknade. - Trevägseditorn tar filer upp till 20 000 rader per sida; över det avstår den och säger varför. - Klipp en diff vid 50 000 rader. - Loggen hämtas hundra revisioner åt gången. ## 6. Så verifieras det Ett steg är klart när alla fyra gäller: 1. Releasebygget går igenom utan varningar i egen kod. 2. Testerna går igenom. De ska täcka, mot ett riktigt repo: status för varje tillstånd, diff (ändrad, tillagd, borttagen, binär, egenskaper), commit av ett urval, update med en andra arbetskopia som checkar in, revert, delete, rename, logg i omgångar, listning, utcheckning, ny katalog i repot, fjärrtillstånd, konflikter (text och träd), sammanfogning av en konflikt ur svn:s tre filer, och avbrott. Sammanfogningen testas dessutom för sig: ändringar på var sin sida, krockar, samma ändring på båda håll, tillägg först och sist, tomma texter, och att varje sida går att återskapa exakt. Använd filnamn med mellanslag, å/ä/ö och `@`. 3. Bunten byggs och signeras. 4. Gränssnittet är granskat i en skärmbild tagen av appen själv. Kommandon som ändrar något provas bara mot repon som testet eller provkörningen själv skapat, aldrig mot riktiga arbetskopior. Det som bara går att bedöma med mus och ögon, och allt mot en riktig server, provas av en människa. ## 7. Arbetssätt - **Plan först.** Låt verktyget undersöka förebilden, föreslå språk och motor med skäl, och skriva en plan innan någon kod skrivs. - **Ett ärende per funktion**, i en ärendehanterare eller en enkel lista: vad användaren ska kunna göra, var i gränssnittet, och vad som inte ingår. Bygg ett i taget, i ordning: status, diff, commit, kommandon, logg, repository browser, inkommande, konflikter, automatisk omläsning, ikon, trevägseditor. - **Skriv in vad som mättes** när ett ärende stängs, och vad som inte gick att prova. - **Håll resonemangen i repot**: en `docs/research.md` med avvägningarna och det som visade sig fel, och en instruktionsfil till verktyget med arkitekturen, verifieringskedjan och reglerna. - **Fråga om verkliga beslut**, inte om sådant som har ett rimligt standardval. ## 8. Prompten ``` Jag vill bygga en grafisk klient för Subversion för macOS. Läs IDEA.md, som jag bifogar, i sin helhet innan du gör något: den beskriver vad som ska byggas, vilka beslut som är avgörande och vilka fallgropar som finns. Börja i planläge. Undersök hur [SmartSVN eller en annan förebild] är uppbyggd, kontrollera vad som finns installerat på min maskin (svn, Swift, Xcode eller bara Command Line Tools) och föreslå en plan. Följ stacken i IDEA.md om du inte hittar ett skäl att avvika; säg i så fall varför. Appen ska heta [namn] och ha bundle-id [t.ex. se.exempel.Namn]. Gränssnittet ska vara på [engelska], kommentarer och dokumentation på [svenska]. Dela upp arbetet i ärenden enligt avsnitt 7 och håll dem i [ärendehanterare eller en fil TODO.md]. Bygg ett ärende i taget. Ett ärende är klart först när verifieringen i avsnitt 6 är gjord, och skriv då in vad du mätte och vad du inte kunde prova. Kör aldrig kommandon som ändrar något mot mina riktiga arbetskopior i [katalog]. Skapa egna provrepon med svnadmin create. Checka inte in något åt mig. Bygg in skärmbildskroken från avsnitt 3 redan i första ärendet, och granska varje ändring i gränssnittet i en skärmbild innan du säger att den är klar. ```