undefined

如果输出非空，询问用户：
> *“您有未提交的变更。我应该先暂存它们（`git stash`），还是您先提交这些变更？”*

```bash

```bash

如果构建失败，停止操作。请用户先修复现有问题。

---

undefined

**确定目标版本**。有两种路径：

**路径A — 用户传入了目标版本参数（`$ARGUMENTS`）：**

在使用前先验证其是否符合已发布的版本。必须通过以下**全部三项**检查：

```bash

1. **存在性** — 请求的标签出现在上述已发布版本列表中。
2. **主版本正确** — 标签属于**v3**主版本系列（以`3`开头）。`2.x`或其他主版本无效，需拒绝。
3. **非降级** — 标签版本比项目中检测到的当前版本更新。

> **如果任何一项检查失败，立即停止并询问用户**。不要静默回退。例如：
> - *“`3.9.9`不是已发布的Auth0.swift版本。已发布的v3版本包括：`3.0.0-beta.2`，……。请传入有效的v3标签，或省略参数以自动选择最新的v3版本。”*
> - *“`2.10.0`是v2版本，不是v3版本。该工具仅用于迁移到v3版本。请传入v3标签（例如`3.0.0-beta.2`）或省略参数。”*
> - *“`3.0.0-beta.1`比您项目中已有的`3.0.0-beta.2`版本旧——这属于降级操作。请传入更新的v3标签或省略参数。”*

**路径B — 无参数：自动选择最新的v3版本（包括预发布版本）：**

```bash

将结果记录为`<TARGET_TAG>`，并在后续所有步骤中使用。

> **如果`<TARGET_TAG>`是预发布版本**（包含`-beta`、`-rc`等），在继续前告知用户：
> *“最新的v3版本是`<TARGET_TAG>`（预发布版）。我将迁移到该版本。您可以通过传入参数指定其他标签：`auth0-swift-major-migration <tag>`。”*
>
> **如果不存在v3版本**（解析结果为空），停止操作并告知用户没有可迁移的已发布v3版本。


---

TAG=<TARGET_TAG>   # 开发者在步骤2中选择的版本，例如3.0.0-beta.2

读取获取到的源码并记录：
- 所有变更的公开方法签名（返回类型、参数、新增`throws`）
- 重命名或移除的类型
- 变更的协议要求
- 变更的默认参数值

这是最根本的依据。第6步中的所有变更必须与这些文件中的实际签名一致。

---

grep -rl "import Auth0" --include="*.swift" .

// 稳定v3版本 — 范围指定符会自动获取所有3.x.y补丁版本
.package(url: "https://github.com/auth0/Auth0.swift", from: "3.0.0")

// 预发布/特定beta版本 — 需要精确标签
.package(url: "https://github.com/auth0/Auth0.swift", exact: "3.0.0-beta.2")

swift package resolve

// 稳定v3版本
pod 'Auth0', '~> 3.0'

// 预发布/特定beta版本 — 固定精确版本
pod 'Auth0', '3.0.0-beta.2'

pod update Auth0

// 稳定v3版本
github "auth0/Auth0.swift" ~> 3.0

// 预发布/特定beta版本 — 固定精确标签
github "auth0/Auth0.swift" "3.0.0-beta.2"

carthage update Auth0.swift --use-xcframeworks

// v2
Auth0.webAuth().clearSession { result in
    switch result {
    case .success: handleLogoutSuccess()
    case .failure(let error): handleError(error)
    }
}

// v3
Auth0.webAuth().logout { result in
    switch result {
    case .success: handleLogoutSuccess()
    case .failure(let error): handleError(error)
    }
}

// v2
try await Auth0.webAuth().clearSession()

// v3
try await Auth0.webAuth().logout()

// v2
Auth0.webAuth().clearSession()
    .sink(receiveCompletion: { ... }, receiveValue: { ... })
    .store(in: &cancellables)

// v3
Auth0.webAuth().logout()
    .sink(receiveCompletion: { ... }, receiveValue: { ... })
    .store(in: &cancellables)

// v2
try await Auth0.webAuth().clearSession(federated: true)

// v3
try await Auth0.webAuth().logout(federated: true)

// v2 — 包含已不存在枚举值的穷举switch
Auth0.webAuth().start { result in
    switch result {
    case .success(let credentials):
        handle(credentials)
    case .failure(let error):
        switch error {
        case .userCancelled:
            break  // 用户取消操作——无需处理
        case .pkceNotAllowed:
            // ❌ v3中编译错误——移除该枚举值
            showConfigError("PKCE not allowed")
        default:
            showError(error)
        }
    }
}

// v3 — 删除已移除的枚举值；按需处理新增的枚举值
Auth0.webAuth().start { result in
    switch result {
    case .success(let credentials):
        handle(credentials)
    case .failure(let error):
        switch error {
        case .userCancelled:
            break  // 用户取消操作——无需处理
        case .authenticationFailed:
            // 服务端拒绝登录——显示合适的提示信息
            showError("登录失败，请检查您的凭据。")
        case .codeExchangeFailed:
            // 令牌交换失败——网络或服务端问题
            showError("出现错误，请重试。")
        case .credentialsManagerError:
            // 登录成功但无法存储凭据
            // 用户在内存中已认证，但下次启动需重新登录
            // 可通过error.cause访问底层错误（WebAuthError.cause: Error?）
            reportToMonitoring(error.cause)
            showError("无法保存您的会话。")
        default:
            showError(error)
        }
    }
}

// v2
do {
    let credentials = try await Auth0.webAuth().start()
    handle(credentials)
} catch WebAuthError.userCancelled {
    break
} catch WebAuthError.pkceNotAllowed {
    // ❌ v3中编译错误——移除该catch块
    showConfigError()
} catch {
    showError(error)
}

// v3 — 删除已移除的枚举值；如果项目需要处理新增枚举值则添加
 do {
    let credentials = try await Auth0.webAuth().start()
    handle(credentials)
} catch WebAuthError.userCancelled {
    break
} catch WebAuthError.authenticationFailed {
    showError("登录失败，请检查您的凭据。")
} catch WebAuthError.codeExchangeFailed {
    showError("出现错误，请重试。")
} catch {
    showError(error)
}

// v2 — 手动调度到主线程
credentialsManager.credentials { result in
    DispatchQueue.main.async {
        switch result {
        case .success(let credentials):
            self.accessToken = credentials.accessToken
            self.isAuthenticated = true
        case .failure(let error):
            self.authError = error
        }
    }
}

// v3 — 回调已在主线程返回
credentialsManager.credentials { result in
    switch result {
    case .success(let credentials):
        self.accessToken = credentials.accessToken
        self.isAuthenticated = true
    case .failure(let error):
        self.authError = error
    }
}

// v2
let credentials = try await Auth0.webAuth().start()
await MainActor.run {
    self.isAuthenticated = true
}

// v3 — start()是@MainActor方法；await后已处于主线程
let credentials = try await Auth0.webAuth().start()
self.isAuthenticated = true

// v2 — 将请求存储为带类型的变量
let request: Request<Credentials, AuthenticationError> = Auth0
    .authentication()
    .login(usernameOrEmail: email, password: password,
           realmOrConnection: "Username-Password-Authentication",
           audience: audience, scope: scope)
request.start { result in ... }

// v3 — 将类型注解更新为协议类型
// 对于返回凭据的方法：
let request: any TokenRequestable<Credentials, AuthenticationError> = Auth0
    .authentication()
    .login(usernameOrEmail: email, password: password,
           realmOrConnection: "Username-Password-Authentication",
           audience: audience, scope: scope)
request.start { result in ... }

// 对于非凭据方法（signup、resetPassword、userInfo、jwks）：
let request: any Requestable<DatabaseUser, AuthenticationError> = Auth0
    .authentication()
    .signup(email: email, password: password, connection: connection)
request.start { result in ... }

// 最常见的模式——直接链式调用，无需注解，无需修改：
Auth0.authentication()
    .login(usernameOrEmail: email, password: password,
           realmOrConnection: "Username-Password-Authentication",
           audience: audience, scope: scope)
    .start { result in ... }  // ✅ 无需修改

// v2 — 测试中的mock Authentication协议实现
class MockAuthentication: Authentication {
    var credentialsResult: Result<Credentials, AuthenticationError> = .failure(.init(info: [:], statusCode: 0))

    func login(usernameOrEmail username: String,
               password: String,
               realmOrConnection realm: String,
               audience: String?,
               scope: String) -> Request<Credentials, AuthenticationError> {
        // ❌ v3中编译错误——Request不再是返回类型
        return Request(session: URLSession.shared, ...) // v2内部实现——不再可用
    }
}

// v2 — 用作stub的mock Requestable
struct MockRequest<T, E: Auth0Error>: Requestable {
    let result: Result<T, E>
    func start(_ callback: @escaping (Result<T, E>) -> Void) {
        // ❌ 缺少@MainActor——不符合v3的Requestable协议
        callback(result)
    }
}

// v3 — 更新后的mock
struct MockRequest<T, E: Auth0Error>: Requestable {
    let result: Result<T, E>
    // ✅ 添加@MainActor以匹配协议；通过Task调度满足@MainActor隔离要求
    func start(_ callback: @escaping @MainActor (Result<T, E>) -> Void) {
        Task { @MainActor in callback(result) }
    }
}

// v3 — 更新后的Authentication mock，返回正确的协议类型
class MockAuthentication: Authentication {
    var credentialsResult: Result<Credentials, AuthenticationError> = .failure(.init(info: [:], statusCode: 0))

    func login(usernameOrEmail username: String,
               password: String,
               realmOrConnection realm: String,
               audience: String?,
               scope: String) -> any TokenRequestable<Credentials, AuthenticationError> {
        // ✅ 返回MockTokenRequest，而非Request
        return MockTokenRequest(result: credentialsResult)
    }
}

// v3 — TokenRequestable mock（用于返回凭据的方法）
struct MockTokenRequest<T, E: Auth0Error>: TokenRequestable {
    typealias ResultType = T
    typealias ErrorType = E

    let result: Result<T, E>

    func start(_ callback: @escaping @MainActor (Result<T, E>) -> Void) {
        Task { @MainActor in callback(result) }
    }

    // TokenRequestable新增了这些声明验证构建器方法——返回self即可
    func validateClaims() -> any TokenRequestable<T, E> { self }
    func withLeeway(_ leeway: Int) -> any TokenRequestable<T, E> { self }
    func withIssuer(_ issuer: String) -> any TokenRequestable<T, E> { self }
    func withNonce(_ nonce: String?) -> any TokenRequestable<T, E> { self }
    func withMaxAge(_ maxAge: Int?) -> any TokenRequestable<T, E> { self }
    func withOrganization(_ organization: String?) -> any TokenRequestable<T, E> { self }
}

// v2
if credentialsManager.store(credentials: credentials) {
    print("存储成功")
} else {
    print("存储失败")
}

// v3 — 使用do-catch；将错误映射到项目现有的错误处理逻辑
do {
    try credentialsManager.store(credentials: credentials)
} catch {
    // 替换为项目已有的日志/错误处理逻辑
    handleError(error)
}

// v2 — 静默忽略返回值
_ = credentialsManager.store(credentials: credentials)

// v3 — try?同样会忽略错误；如果项目之前未处理失败则使用该方式
try? credentialsManager.store(credentials: credentials)

// v2
_ = credentialsManager.clear()
_ = credentialsManager.clear(forAudience: "https://api.example.com")

// v3
try? credentialsManager.clear()
try? credentialsManager.clear(forAudience: "https://api.example.com")
// 或者，如果项目需要处理错误：
do {
    try credentialsManager.clear()
} catch {
    handleError(error)
}

// v2 — 属性访问，返回UserInfo?
func currentUser() -> UserInfo? {
    return credentialsManager.user
}

// v3 — 抛出方法调用，返回UserProfile?
func currentUser() -> UserProfile? {
    return try? credentialsManager.userProfile()
}

// v3 — 如果项目需要暴露错误：
func loadUser() throws {
    let profile = try credentialsManager.userProfile()
    self.userProfile = profile
}

// v2 — 仅可能出现.revokeFailed；无凭据时会静默返回.success
credentialsManager.revoke { result in
    switch result {
    case .success:
        navigateToLogin()
    case .failure(let error):
        showError(error)  // 仅.revokeFailed会进入此处
    }
}

// v3 — 新增错误会暴露；如果项目检查特定错误则更新switch
credentialsManager.revoke { result in
    switch result {
    case .success:
        navigateToLogin()
    case .failure(let error):
        switch error {
        case .noCredentials:
            // 无存储的凭据——实际上已登出
            navigateToLogin()
        case .revokeFailed:
            // 服务端撤销失败——刷新令牌可能仍有效
            showError("无法撤销您的会话，请重试。")
        case .clearFailed:
            // 服务端令牌已撤销但Keychain删除失败
            // 视为已登出——令牌在服务端已失效
            navigateToLogin()
        default:
            showError(error)
        }
    }
}

// v3 — 如果项目需要区分存储失败和网络失败：
credentialsManager.credentials { result in
    switch result {
    case .success(let credentials):
        use(credentials)
    case .failure(let error):
        switch error {
        case .noCredentials, .renewFailed:
            // 凭据缺失或续期失败——强制重新登录
            navigateToLogin()
        case .storeFailed:
            // 续期成功但无法保存——本次会话内存中的凭据有效
            // 用户下次启动需重新登录
            reportToMonitoring(error)
            use(/* 如果可用，使用最后已知的凭据 */)
        default:
            showError(error)
        }
    }
}

// v2
var currentUser: UserInfo?
func showProfile(_ profile: UserInfo) { ... }
func fetchUser() -> UserInfo? { ... }

// v3
var currentUser: UserProfile?
func showProfile(_ profile: UserProfile) { ... }
func fetchUser() -> UserProfile? { ... }

// v2 — 返回Request<UserInfo, AuthenticationError>
Auth0.authentication()
    .userInfo(withAccessToken: accessToken)
    .start { (result: Result<UserInfo, AuthenticationError>) in ... }

// v3 — 返回Request<UserProfile, AuthenticationError>
Auth0.authentication()
    .userInfo(withAccessToken: accessToken)
    .start { (result: Result<UserProfile, AuthenticationError>) in ... }