Add a project straight from a remote repository URL

Sidebar ⊕ → Clone Repository…: paste a git URL, pick where it lands
(remembered across clones), optionally a folder name, branch, or depth.
GitClient streams `git clone --progress` so the sheet shows git's own
progress line; a failure keeps the sheet open with git's explanation,
https credentials are redacted from everything shown, a partial clone
the run created is removed, and git is never allowed to prompt — no tty
means fail fast, not hang. Success routes through the exact .openProject
path a picked folder takes, so nothing downstream knows the project
began as a URL. Drawn on supacode's clone form (shape, not code).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: scgopi

graphcode/Sources/Clients/GitClient.swift

@@ -3,16 +3,27 @@ import Foundation
 import GraphcodeKit
 import os
 
-/// Graphcode's own minimal git client — create/list/remove a worktree, nothing more.
-/// A `LoopNode`'s `worktreeBinding` is the only thing that needs this; it is not a
-/// general git porcelain layer. See docs/03-architecture.md and
-/// docs/07-roadmap.md#phase-1--single-loop-manual-check.
+/// Graphcode's own minimal git client — worktrees, and cloning a remote repository so a
+/// project can be added straight from a URL. It is not a general git porcelain layer.
+/// See docs/03-architecture.md and docs/07-roadmap.md#phase-1--single-loop-manual-check.
 struct GitClient: Sendable {
   var createWorktree:
     @Sendable (_ repositoryPath: String, _ worktreePath: String, _ branch: String) async throws ->
       WorktreeRef
   var listWorktrees: @Sendable (_ repositoryPath: String) async throws -> [WorktreeRef]
   var removeWorktree: @Sendable (_ worktree: WorktreeRef) async throws -> Void
+  /// Streams a `git clone --progress` into `destination`: progress lines while it runs,
+  /// `.finished` on success, a thrown `GitClientError` on failure. The drawn-on shape is
+  /// supacode's `cloneStream` (structure, not code): streaming is what lets the form show
+  /// a live percentage instead of a spinner over a multi-minute network operation.
+  var clone:
+    @Sendable (_ url: String, _ destination: URL, _ branch: String?, _ depth: Int?) ->
+      AsyncThrowingStream<GitCloneEvent, any Error>
+}
+
+enum GitCloneEvent: Equatable, Sendable {
+  case progress(String)
+  case finished
 }
 
 enum GitClientError: Error, Equatable {
@@ -38,10 +49,168 @@ extension GitClient: DependencyKey {
     removeWorktree: { worktree in
       _ = try await run(
         "git", ["-C", worktree.repositoryPath, "worktree", "remove", worktree.worktreePath])
+    },
+    clone: { url, destination, branch, depth in
+      runClone(url: url, destination: destination, branch: branch, depth: depth)
     }
   )
 }
 
+extension GitClient {
+  /// Git's own "humanish" directory name for a clone URL — the last path component with
+  /// `.git` stripped. Parsed from the raw string because scp-style remotes
+  /// (`git@host:org/repo.git`) are not URLs Foundation can take apart. Empty when no
+  /// leaf derives, which the form treats as "nothing to prefill".
+  static func humanishName(forCloneURL url: String) -> String {
+    var trimmed = url.trimmingCharacters(in: .whitespacesAndNewlines)
+    if let queryIndex = trimmed.firstIndex(where: { $0 == "?" || $0 == "#" }) {
+      trimmed = String(trimmed[..<queryIndex])
+    }
+    while trimmed.hasSuffix("/") { trimmed.removeLast() }
+    if let separatorIndex = trimmed.lastIndex(where: { $0 == "/" || $0 == ":" }) {
+      trimmed = String(trimmed[trimmed.index(after: separatorIndex)...])
+    }
+    if trimmed.hasSuffix(".git") { trimmed.removeLast(4) }
+    return trimmed
+  }
+
+  /// The secret userinfo of an http(s) clone URL (`token` or `user:password`), so it can
+  /// be blanked out of every progress line and error shown to a human. An ssh user
+  /// (`git@host`) is a login name, not a secret, and URLComponents doesn't parse
+  /// scp-style remotes anyway — both fall out as nil.
+  static func cloneCredentials(of url: String) -> String? {
+    guard let components = URLComponents(string: url),
+      let user = components.percentEncodedUser, !user.isEmpty
+    else { return nil }
+    guard let password = components.percentEncodedPassword, !password.isEmpty else {
+      return user
+    }
+    return "\(user):\(password)"
+  }
+}
+
+/// The live `clone` implementation. Progress arrives on stderr in `\r`-separated
+/// updates (git redraws one line in place), so the reader splits on both `\r` and `\n`
+/// and yields each completed piece.
+private func runClone(
+  url: String, destination: URL, branch: String?, depth: Int?
+) -> AsyncThrowingStream<GitCloneEvent, any Error> {
+  AsyncThrowingStream { continuation in
+    let destinationPath = destination.standardizedFileURL.path
+    // Only a directory the clone itself created is ours to remove on failure — a
+    // pre-existing one (git will refuse it anyway if non-empty) is the user's.
+    let existedBefore = FileManager.default.fileExists(atPath: destinationPath)
+    let credentials = GitClient.cloneCredentials(of: url)
+
+    let process = cloneProcess(
+      url: url, destinationPath: destinationPath, branch: branch, depth: depth)
+    let stdout = Pipe()
+    let stderr = Pipe()
+    process.standardOutput = stdout
+    process.standardError = stderr
+
+    // Collected for the error message: git's explanation of a failure is its last few
+    // stderr lines, and `commandFailed` should carry them rather than a bare status.
+    let recentLines = OSAllocatedUnfairLock(initialState: [String]())
+    let onLine: @Sendable (String) -> Void = { line in
+      let shown =
+        credentials.map { line.replacingOccurrences(of: $0, with: "•••") } ?? line
+      recentLines.withLock { recent in
+        recent.append(shown)
+        if recent.count > 5 { recent.removeFirst() }
+      }
+      continuation.yield(.progress(shown))
+    }
+    attachLineReader(to: stdout, onLine: onLine)
+    attachLineReader(to: stderr, onLine: onLine)
+
+    process.terminationHandler = { process in
+      stdout.fileHandleForReading.readabilityHandler = nil
+      stderr.fileHandleForReading.readabilityHandler = nil
+      if process.terminationStatus == 0 {
+        continuation.yield(.finished)
+        continuation.finish()
+        return
+      }
+      // A failed clone that created the directory leaves a partial repo the next
+      // attempt would refuse; remove what this run made and nothing else.
+      if !existedBefore {
+        try? FileManager.default.removeItem(atPath: destinationPath)
+      }
+      continuation.finish(
+        throwing: GitClientError.commandFailed(
+          command: "git clone",
+          status: process.terminationStatus,
+          output: recentLines.withLock { $0.joined(separator: "\n") }))
+    }
+
+    continuation.onTermination = { reason in
+      // The sheet was dismissed mid-clone: end the process; its termination handler
+      // then does the partial-clone cleanup.
+      if case .cancelled = reason, process.isRunning { process.terminate() }
+    }
+
+    do {
+      try process.run()
+    } catch {
+      continuation.finish(throwing: error)
+    }
+  }
+}
+
+/// The `git clone` invocation, environment included.
+private func cloneProcess(
+  url: String, destinationPath: String, branch: String?, depth: Int?
+) -> Process {
+  var arguments = ["git", "clone", "--progress"]
+  if let branch, !branch.isEmpty { arguments += ["--branch", branch] }
+  if let depth { arguments += ["--depth", String(depth)] }
+  arguments += [url, destinationPath]
+
+  let process = Process()
+  process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+  process.arguments = arguments
+  var environment = ProcessInfo.processInfo.environment
+  // No tty means no one to answer a prompt: fail fast on credentials and host keys
+  // instead of hanging the sheet on a question it can never show.
+  environment["GIT_TERMINAL_PROMPT"] = "0"
+  environment["GIT_SSH_COMMAND"] =
+    "ssh -o BatchMode=yes -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new"
+  // Untranslated output, so the progress parsing and the errors people paste into
+  // issues are the same everywhere.
+  environment["LC_ALL"] = "C"
+  process.environment = environment
+  return process
+}
+
+/// Feeds `onLine` every completed line out of `pipe`, treating `\r` (git's redraw-in-
+/// place separator) the same as `\n`, and dropping blanks.
+private func attachLineReader(to pipe: Pipe, onLine: @escaping @Sendable (String) -> Void) {
+  let remainder = OSAllocatedUnfairLock(initialState: "")
+  pipe.fileHandleForReading.readabilityHandler = { handle in
+    let chunk = handle.availableData
+    guard !chunk.isEmpty else {
+      handle.readabilityHandler = nil
+      return
+    }
+    guard let text = String(data: chunk, encoding: .utf8) else { return }
+    let pieces = remainder.withLock { remainder in
+      var buffered = remainder + text
+      var lines: [String] = []
+      while let breakIndex = buffered.firstIndex(where: { $0 == "\r" || $0 == "\n" }) {
+        lines.append(String(buffered[..<breakIndex]))
+        buffered = String(buffered[buffered.index(after: breakIndex)...])
+      }
+      remainder = buffered
+      return lines
+    }
+    for piece in pieces {
+      let line = piece.trimmingCharacters(in: .whitespaces)
+      if !line.isEmpty { onLine(line) }
+    }
+  }
+}
+
 extension DependencyValues {
   var gitClient: GitClient {
     get { self[GitClient.self] }

graphcode/Sources/Features/App/AppSidebarView.swift

@@ -85,6 +85,16 @@ struct AppSidebarView: View {
     ) { result in
       store.send(.welcome(.folderPickerResult(result)))
     }
+    // The clone sheet. Dismissing it mid-clone cancels the clone — that's
+    // `.cloneCancelled`'s job, not a side effect of the binding.
+    .sheet(
+      isPresented: Binding(
+        get: { store.welcome.cloneDraft != nil },
+        set: { if !$0 { store.send(.welcome(.cloneCancelled)) } }
+      )
+    ) {
+      CloneRepositoryFormView(store: store.scope(state: \.welcome, action: \.welcome))
+    }
     .confirmationDialog(
       "Delete this project's loops?",
       isPresented: Binding(
@@ -126,6 +136,13 @@ struct AppSidebarView: View {
       } label: {
         Label("Open Folder…", systemImage: "folder")
       }
+      // A project can also start as a URL — the clone lands locally and opens through
+      // the same path a picked folder takes. See `WelcomeFeature.CloneDraft`.
+      Button {
+        store.send(.welcome(.cloneRepositoryButtonTapped))
+      } label: {
+        Label("Clone Repository…", systemImage: "square.and.arrow.down.on.square")
+      }
       if !store.welcome.recentProjects.isEmpty {
         Divider()
         ForEach(store.welcome.recentProjects) { project in

graphcode/Sources/Features/Welcome/CloneRepositoryFormView.swift

@@ -0,0 +1,108 @@
+import ComposableArchitecture
+import GraphcodeKit
+import SwiftUI
+
+/// The clone-a-remote-repository sheet — paste a URL, pick where it lands, and the
+/// finished clone opens as an ordinary project. Progress streams into the sheet and a
+/// failure keeps it open with git's own explanation, so a typo'd URL costs a retry
+/// rather than a reopened form.
+struct CloneRepositoryFormView: View {
+  @Bindable var store: StoreOf<WelcomeFeature>
+
+  var body: some View {
+    VStack(spacing: 12) {
+      Text("Clone Repository").font(.headline)
+
+      Form {
+        TextField(
+          "Repository", text: repositoryURL,
+          prompt: Text("https://github.com/you/repo.git")
+        )
+        .autocorrectionDisabled()
+        .font(.system(.body, design: .monospaced))
+
+        HStack(spacing: 6) {
+          TextField("Location", text: locationPath, prompt: Text("where the clone lands"))
+            .font(.system(.body, design: .monospaced))
+          Button("Choose…") {
+            store.send(.binding(.set(\.isCloneLocationPickerPresented, true)))
+          }
+        }
+
+        TextField(
+          "Folder", text: folderName,
+          prompt: Text(derivedFolderPlaceholder))
+
+        TextField("Branch", text: branch, prompt: Text("default branch — optional"))
+        TextField("Depth", text: depth, prompt: Text("full history — optional"))
+          .font(.system(.body, design: .monospaced))
+      }
+      .formStyle(.columns)
+      .fixedSize(horizontal: false, vertical: true)
+
+      // One line of status: the live progress while cloning, the failure after one,
+      // nothing otherwise. Progress lines are git's own (`Receiving objects: 42% …`).
+      if let progress = store.cloneDraft?.progressLine, store.cloneDraft?.isCloning == true {
+        Text(progress)
+          .font(.caption.monospacedDigit())
+          .foregroundStyle(.secondary)
+          .lineLimit(1)
+          .frame(maxWidth: .infinity, alignment: .leading)
+      }
+      if let failure = store.cloneDraft?.failureMessage {
+        Text(failure)
+          .font(.caption)
+          .foregroundStyle(.red)
+          .textSelection(.enabled)
+          .frame(maxWidth: .infinity, alignment: .leading)
+      }
+
+      HStack {
+        Button("Cancel") { store.send(.cloneCancelled) }
+        Spacer()
+        if store.cloneDraft?.isCloning == true {
+          ProgressView().controlSize(.small).padding(.trailing, 4)
+        }
+        Button("Clone") { store.send(.cloneSubmitted) }
+          .keyboardShortcut(.defaultAction)
+          .disabled(store.cloneDraft?.canSubmit != true)
+      }
+    }
+    .padding(24)
+    .frame(width: 460)
+    .fileImporter(
+      isPresented: $store.isCloneLocationPickerPresented,
+      allowedContentTypes: [.folder]
+    ) { result in
+      store.send(.cloneLocationPicked(result.mapError { $0 }))
+    }
+  }
+
+  private var derivedFolderPlaceholder: String {
+    let derived = store.cloneDraft?.derivedFolderName ?? ""
+    return derived.isEmpty ? "derived from the URL" : derived
+  }
+
+  // Bindings into the optional draft. Writing into a dismissed sheet's draft is a
+  // no-op rather than a crash, matching how the reducer treats its own optionals.
+  private var repositoryURL: Binding<String> {
+    draftBinding(\.repositoryURL)
+  }
+  private var locationPath: Binding<String> { draftBinding(\.locationPath) }
+  private var folderName: Binding<String> { draftBinding(\.folderName) }
+  private var branch: Binding<String> { draftBinding(\.branch) }
+  private var depth: Binding<String> { draftBinding(\.depth) }
+
+  private func draftBinding(
+    _ keyPath: WritableKeyPath<WelcomeFeature.CloneDraft, String>
+  ) -> Binding<String> {
+    Binding(
+      get: { store.cloneDraft?[keyPath: keyPath] ?? "" },
+      set: { newValue in
+        guard var draft = store.cloneDraft else { return }
+        draft[keyPath: keyPath] = newValue
+        store.send(.binding(.set(\.cloneDraft, draft)))
+      }
+    )
+  }
+}