docs/superpowers/plans/2026-09-06-mr07-repo-actions.md

MR 7: Repository actions — fork, watch/mute, bookmark Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Close three parity rows — fork, watch, mute, and bookmark, bookmark list.

Architecture: Three repository-level actions on one screen, all thin writes over existing commands. The complication is that the server reports back almost none of the resulting state, so each of the three gets a different treatment depending on what is actually readable.

Spec: docs/superpowers/specs/2026-09-06-ios-parity-design.md

What the server does and does not report

This shaped every decision below, and it is worth stating plainly because it is not what the spec assumed.

State	Readable?	Consequence
Watch / mute	No. store.RepoWatchState exists but is internal; no command exposes it	Two stateless actions, not a toggle
Bookmarked	Indirectly — repo bookmarks lists them, membership is derivable	A real toggle, at the cost of one list read
fork_of	No on repo show; only on repo fork's own response (internal/control/mr.go:94)	Cannot show "forked from X" for an existing repository

Filed upstream as krz/gitbay#178. Do not work around any of it by inventing local persistence — the app renders server state; it does not remember its own.

Global Constraints

• Swift 6 language mode, default MainActor isolation. Wire models are nonisolated structs.
• Swift Testing only — never XCTest.
• gitbayTests is hermetic and offline; network goes through StubProtocol.
• New files under gitbay/ and gitbayTests/ need no project.pbxproj edit.
• The label model is IssueLabel; the notification model is InboxNotification. Neither shadows a framework type, and neither should be renamed back.
• Never mention Claude, LLMs or AI in commits, comments, or the merge request. No Co-Authored-By trailer.
• Never commit to main.

The commands, verbatim from the registry:

repo fork       <owner/name> [--name <n>]
repo watch      <owner/name>
repo unwatch    <owner/name>
repo bookmark   <owner/name>
repo unbookmark <owner/name>
repo bookmarks

Note repo bookmarks — plural, and it takes no argument. It is not repo bookmark list.

repo fork returns {"path": "<new owner/name>", "fork_of": "<source>"}.

Counting tests:

grep -cE "^Test case '[^']*' passed" /tmp/out.txt
grep -cE "^Test case '[^']*' failed" /tmp/out.txt
grep -cE "^Test case '[^']*' skipped" /tmp/out.txt

Baseline: 297 passed, 1 skipped, 0 failed.

---

File Structure

File	Responsibility
gitbay/Repos/RepoActionsViewModel.swift (create)	ForkResult model, bookmark state, and the five actions
gitbayTests/RepoActionTests.swift (create)	Every test in this plan
gitbay/Views/Repos/RepoView.swift (modify)	The actions, in the repository's menu

---

Task 1: The actions and the bookmark state

Files: Create gitbay/Repos/RepoActionsViewModel.swift; test in gitbayTests/RepoActionTests.swift

Interfaces produced:

• nonisolated struct ForkResult: Decodable, Sendable, Hashable — path: String, forkOf: String
• @Observable @MainActor final class RepoActionsViewModel — isBookmarked: Bool?, actionError: String?, notice: String?, working: Bool, func loadBookmarkState() async, func setBookmarked(_:) async, func watch() async, func unwatch() async, func fork(named:) async -> ForkResult?

Behaviour, each pinned by a test:

1. repo bookmarks takes no repository argument — argv is exactly ["repo", "bookmarks"]. Passing the path would be a usage error.
2. isBookmarked is Bool?: nil until known. It is derived by testing membership of the repo bookmarks result, and a failed load leaves it nil rather than false — "we don't know" and "not bookmarked" are different, and the UI must not claim the latter when it means the former. This is the same three-state lesson MRs 4 and 5 each had to learn.
3. setBookmarked(true) sends repo bookmark; setBookmarked(false) sends repo unbookmark. Two commands, not a flag.
4. watch() and unwatch() send their commands and report the result. They do not attempt to track state — nothing reports it back, and inventing a local guess would show the user something the server never said.
5. fork(named:) sends ["repo", "fork", repoPath], appending --name <n> only when a name is given, and returns the decoded ForkResult so the caller can navigate to the new repository.
6. A refusal surfaces into actionError and does not clear a prior success notice misleadingly.

• Step 1: Write the failing tests

import Foundation
import Testing
@testable import gitbay

private func makeClient() throws -> (GitbayClient, StubProtocol.Box) {
    let box = StubProtocol.box()
    let client = GitbayClient(
        instance: try GitbayInstance(url: "https://gitbay.org"),
        token: "test-token",
        session: box.session()
    )
    return (client, box)
}

private func argvFrom(_ url: URL) -> [String] {
    URLComponents(url: url, resolvingAgainstBaseURL: false)?
        .queryItems?.filter { $0.name == "argv" }.compactMap(\.value) ?? []
}

private func argvOf(_ seen: StubProtocol.Seen) throws -> [String] {
    let body = try #require(try JSONSerialization.jsonObject(with: seen.body) as? [String: Any])
    return try #require(body["argv"] as? [String])
}

private let bookmarks = """
    {"protocol_version":1,"data":[{"path":"krz/gitbay","visibility":"public"},\
    {"path":"krz/solar","visibility":"public"}],"exit_code":0}
    """
private let ok = """
    {"protocol_version":1,"exit_code":0}
    """

@MainActor
struct RepoActionsTests {

    /// `repo bookmarks` is plural and takes NO repository argument.
    @Test func theBookmarkListingTakesNoArgument() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: bookmarks))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        await model.loadBookmarkState()

        #expect(argvFrom(try #require(stub.seen.last).url) == ["repo", "bookmarks"])
        #expect(model.isBookmarked == true)
    }

    @Test func aRepoAbsentFromTheListingIsNotBookmarked() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: bookmarks))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/other")
        await model.loadBookmarkState()

        #expect(model.isBookmarked == false)
    }

    /// "We don't know" is not "not bookmarked". A failed load must leave
    /// the state unknown rather than claiming the repository is not
    /// bookmarked, which would draw the wrong control.
    @Test func aFailedListingLeavesTheStateUnknown() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: """
            {"protocol_version":1,"error":"denied","exit_code":4}
            """))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        await model.loadBookmarkState()

        #expect(model.isBookmarked == nil)
    }

    @Test func bookmarkingAndUnbookmarkingAreDifferentCommands() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: bookmarks))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        await model.loadBookmarkState()

        stub.enqueue(.init(status: 200, json: ok))
        stub.enqueue(.init(status: 200, json: bookmarks))
        await model.setBookmarked(false)
        var write = try #require(stub.seen.first { $0.method == "POST" })
        #expect(try argvOf(write) == ["repo", "unbookmark", "krz/gitbay"])

        let (client2, stub2) = try makeClient()
        stub2.enqueue(.init(status: 200, json: bookmarks))
        let model2 = RepoActionsViewModel(client: client2, repoPath: "krz/other")
        await model2.loadBookmarkState()
        stub2.enqueue(.init(status: 200, json: ok))
        stub2.enqueue(.init(status: 200, json: bookmarks))
        await model2.setBookmarked(true)
        write = try #require(stub2.seen.first { $0.method == "POST" })
        #expect(try argvOf(write) == ["repo", "bookmark", "krz/other"])
    }

    @Test func watchAndUnwatchSendTheirOwnCommands() async throws {
        let (client, stub) = try makeClient()
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")

        stub.enqueue(.init(status: 200, json: ok))
        await model.watch()
        #expect(try argvOf(try #require(stub.seen.last)) == ["repo", "watch", "krz/gitbay"])

        stub.enqueue(.init(status: 200, json: ok))
        await model.unwatch()
        #expect(try argvOf(try #require(stub.seen.last)) == ["repo", "unwatch", "krz/gitbay"])
    }

    @Test func forkingReturnsTheNewPath() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: """
            {"protocol_version":1,"data":{"path":"cmc/gitbay","fork_of":"krz/gitbay"},\
            "exit_code":0}
            """))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        let result = await model.fork(named: nil)

        #expect(result?.path == "cmc/gitbay")
        #expect(result?.forkOf == "krz/gitbay")
        #expect(try argvOf(try #require(stub.seen.last)) == ["repo", "fork", "krz/gitbay"])
    }

    @Test func forkingWithANameAppendsTheFlag() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: """
            {"protocol_version":1,"data":{"path":"cmc/mine","fork_of":"krz/gitbay"},\
            "exit_code":0}
            """))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        _ = await model.fork(named: "mine")

        #expect(try argvOf(try #require(stub.seen.last))
            == ["repo", "fork", "krz/gitbay", "--name", "mine"])
    }

    /// A blank name must not send an empty flag value.
    @Test func forkingWithABlankNameOmitsTheFlag() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: """
            {"protocol_version":1,"data":{"path":"cmc/gitbay","fork_of":"krz/gitbay"},\
            "exit_code":0}
            """))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        _ = await model.fork(named: "   ")

        #expect(try argvOf(try #require(stub.seen.last)) == ["repo", "fork", "krz/gitbay"])
    }

    @Test func aRefusedForkReturnsNilAndSurfaces() async throws {
        let (client, stub) = try makeClient()
        stub.enqueue(.init(status: 200, json: """
            {"protocol_version":1,"error":"a repository named gitbay already exists",\
            "exit_code":1}
            """))
        let model = RepoActionsViewModel(client: client, repoPath: "krz/gitbay")
        let result = await model.fork(named: nil)

        #expect(result == nil)
        #expect(model.actionError?.isEmpty == false)
        #expect(model.working == false)
    }
}

• Step 2: Run to verify failure.
• Step 3: Implement. Copy perform(argv:) from RepoSettingsViewModel for the void writes; fork needs client.run(_:as:) since it decodes a result. Reuse RepoSummary for the bookmarks listing — I checked the live response, {path, description, visibility, bookmarks}, and RepoSummary decodes it directly (the extra bookmarks count is ignored, as Swift's Decodable ignores unknown keys). Do not write a new model.
• Step 4: Run the tests.
• Step 5: Commit — git commit -m "Fork, watch, mute and bookmark a repository"

---

Task 2: The actions on the repository screen

Files: Modify gitbay/Views/Repos/RepoView.swift

No unit tests — UI.

Put all five in the repository screen's toolbar menu, beside the existing pin and archive actions. Study how those are presented and match them.

Each of the three rows gets the treatment its readable state allows:

• Bookmark — a real toggle, because the state is derivable. While isBookmarked is nil the control must not claim either state: show it disabled or as a spinner, never as "not bookmarked". Load the state with .task.
• Watch / Mute — two separate actions, not a toggle. Nothing reports which one is current, so a toggle would be lying. Say what each does rather than implying a state: "Watch this repository" and "Mute this repository". A brief caption noting that the current setting is not shown is honest and cheap; krz/gitbay#178 tracks fixing it properly.
• Fork — an action that prompts for an optional name, then navigates to the new repository on success using RepoRoute.repo(result.path). On refusal, surface the server's message: "already exists" is the common one and the user needs to read it.

RepoView already surfaces actionError-style messages for pin and archive — reuse that, do not add a second notice mechanism.

• Step 1: Bookmark toggle with its unknown state
• Step 2: Watch and Mute as two actions
• Step 3: Fork with an optional name and navigation on success
• Step 4: Build and run the full suite. No drop from 297.
• Step 5: Commit — git commit -m "Repository actions in the repo menu"

---

Task 3: Flip three parity rows and open the merge request

• Step 1: In the Repositories table set fork, watch, mute and bookmark, bookmark list to yes for iOS. Touch no other row.

Land it via a worktree off origin/main in krz/gitbay, merged --strategy ff. That repo requires signed commits, so squash and rebase merges are refused, and its working tree usually holds unrelated work — never switch its branch. Read the merge request number back from mr create's output rather than assuming it.

• Step 2: Run the full suite; record the real number.
• Step 3: Open the merge request, noting that watch and mute ship stateless and why.

---

Notes for whoever executes this

repo bookmarks is plural and takes no argument. Not repo bookmark list, and not repo bookmarks <owner/name>.

Do not invent state the server does not report. Watch and mute have no readable state; a toggle would show the user something the server never said. Two actions is the honest rendering, and krz/gitbay#178 tracks the fix.

nil is not false for the bookmark state. A failed listing means unknown, and drawing "not bookmarked" would be a claim the app cannot support.

fork_of is not on repo show. Do not try to display "forked from X" for an existing repository; it is only on repo fork's own response, which is why the fork action returns it.