diff --git a/apps/desktop/Sources/StimDesktop/Views/RootView.swift b/apps/desktop/Sources/StimDesktop/Views/RootView.swift index 04243a8a6d..170b9a40fc 100644 --- a/apps/desktop/Sources/StimDesktop/Views/RootView.swift +++ b/apps/desktop/Sources/StimDesktop/Views/RootView.swift @@ -426,6 +426,7 @@ struct RootView: View { } else if let path = tutorial.tourPath { navigate(.environment(path), .click("tutorial Show me")) if ["logs", "refresh", "agent"].contains(tutorial.snapshot?.currentStep ?? "") { showsLogs = true } + if tutorial.snapshot?.currentStep == "logs" { TutorialViewerEvents.shared.logsOpened(path) } } }) } diff --git a/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift b/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift index 25317f861a..f7233ab82c 100644 --- a/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift +++ b/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift @@ -278,6 +278,7 @@ struct TutorialPanel: View { case "worktrees": return "Tutorial worktrees removed" case "clone": return "Clone removed and deleted" case "pr": return "Pull request opened" + case "logs": return "Logs opened" default: return PhaseStep.name(id) } } diff --git a/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift b/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift index 733aed9ad6..c158e540dc 100644 --- a/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift +++ b/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift @@ -290,6 +290,11 @@ struct WorkspaceDetail: View { page: page.isUnified ? page : nil, selectedApp: $logWorkspacePath, archive: archive ) .tutorialAnchor(.logsTab, workspace: workspace.path) + .task(id: archive == nil ? (page.isUnified ? logsApp : workspace).path : nil) { + if archive == nil, tutorialHint?.step == "logs" { + TutorialViewerEvents.shared.logsOpened((page.isUnified ? logsApp : workspace).path) + } + } .frame(height: Self.clampedLogsHeight(logsHeight, contentHeight: contentHeight)) } } diff --git a/apps/desktop/Sources/StimKit/TutorialProgress.swift b/apps/desktop/Sources/StimKit/TutorialProgress.swift index e4af902665..6ca536832f 100644 --- a/apps/desktop/Sources/StimKit/TutorialProgress.swift +++ b/apps/desktop/Sources/StimKit/TutorialProgress.swift @@ -15,6 +15,7 @@ public struct TutorialEnvironment: Sendable { public var agentStateDir: String? public var pullRequest: PullRequestFacts? public var iosDoctorRanAt: Date? + public var disk: WorkspaceDisk? public init?(_ workspace: Workspace) { guard let tutorial = workspace.tutorial else { return nil } @@ -28,6 +29,7 @@ public struct TutorialEnvironment: Sendable { lastBuild = workspace.lastBuilds?.ios ios = workspace.ios repository = workspace.worktree?.repository ?? workspace.path + disk = workspace.disk recording = workspace.recording agentStateDir = workspace.agentDevice?.stateDir pullRequest = workspace.worktree?.pullRequest @@ -80,6 +82,51 @@ public enum TutorialViewerEvent: Equatable, Sendable { case input(String) case actionsViewed(String) case replayPlayed(String) + case logsOpened(String) +} + +/// What the tutorial measured while its workspaces existed, kept after Finish and Delete remove them. +public struct TutorialStats: Codable, Equatable, Sendable { + public struct Build: Codable, Equatable, Sendable { + public var durationMs: Double? + /// `local`, `remote`, or `none` when it compiled. + public var cache: String + public var startedAt: Date? + public var finishedAt: Date? + + init(_ build: LastBuild) { + durationMs = build.durationMs + switch build.cacheHit { + case .local: cache = "local" + case .remote: cache = "remote" + case .none: cache = "none" + } + startedAt = parseTimestamp(build.startedAt) + finishedAt = build.finishedAt.flatMap(parseTimestamp) + } + } + + public var firstBuild: Build? + public var secondBuild: Build? + public var agentActions: Int? + /// The largest measured size of each tutorial folder, keyed by path: both worktrees and the clone. + public var worktreeBytes: [String: Double]? + + public init() {} + + /// How much faster the second build finished than the first. + public var savedMs: Double? { + guard let first = firstBuild?.durationMs, let second = secondBuild?.durationMs, first > second else { return nil } + return first - second + } + + /// Whether the second build started before the first one finished. + public var buildsOverlapped: Bool? { + guard let firstEnd = firstBuild?.finishedAt, let secondStart = secondBuild?.startedAt else { return nil } + return secondStart < firstEnd + } + + public var measuredBytes: Double? { worktreeBytes.map { $0.values.reduce(0, +) } } } public struct TutorialRecord: Codable, Equatable, Sendable { @@ -97,6 +144,7 @@ public struct TutorialRecord: Codable, Equatable, Sendable { public var stopped: Bool? public var runPromptCopiedAt: Date? public var phonePairedAtStart: Bool? + public var stats: TutorialStats? public init( version: Int, tourPath: String? = nil, startedAt: Date, step: String = "begin", @@ -245,6 +293,7 @@ public struct TutorialProgress: Sendable { private var viewerInput = false private var actionsViewed = false private var replayPlayed = false + private var logsOpened = false private var details: [String: TutorialNotice] = [:] private var phoneApp = true private var finished: Set = [] @@ -323,6 +372,7 @@ public struct TutorialProgress: Sendable { case .input(let udid) where devices.contains(udid) && viewerOpened: viewerInput = true case .actionsViewed(let udid) where udid == tracked?.ios?.udid: actionsViewed = true case .replayPlayed(let udid) where udid == tracked?.ios?.udid: replayPlayed = true + case .logsOpened(let path) where record?.trackedPaths.contains(path) == true: logsOpened = true default: break } } @@ -356,6 +406,7 @@ public struct TutorialProgress: Sendable { complete(at: completed) } } + recordStats(tracked: tracked, second: second, logs: logs, siblings: input.siblings) let current = record!.step == "done" ? nil : record!.step let steps = TutorialSteps.steps(phoneApp: input.phoneApp).map { step in let state: TutorialStepState = @@ -419,6 +470,38 @@ public struct TutorialProgress: Sendable { ?? "done" } + private mutating func recordStats( + tracked: TutorialEnvironment?, second: TutorialEnvironment?, logs: [LogRecord], siblings: [TutorialEnvironment] + ) { + guard var record else { return } + var stats = record.stats ?? TutorialStats() + let since = record.stepTimes?["build"] ?? record.startedAt + func ok(_ build: LastBuild) -> Bool { + build.status == "ok" && parseTimestamp(build.startedAt).map { $0 >= since } == true + } + if stats.firstBuild == nil, record.done.contains("build"), let tracked { + let first = tracked.builds.reversed().first { ok($0.build) }?.build ?? tracked.lastBuild.flatMap { ok($0) ? $0 : nil } + stats.firstBuild = first.map(TutorialStats.Build.init) + } + if stats.secondBuild == nil, record.done.contains("parallel"), let last = second?.lastBuild, ok(last) { + stats.secondBuild = TutorialStats.Build(last) + } + if let udid = tracked?.ios?.udid { + let count = logs.filter { $0.src == "agent" && $0.event == "agent_action" && $0.deviceId == udid }.count + if count > (stats.agentActions ?? 0) { stats.agentActions = count } + } + let folders = [tracked, second, siblings.first { $0.path == record.clonePath }].compactMap { $0 } + for folder in folders { + if let bytes = folder.disk?.worktreeBytes { + stats.worktreeBytes = (stats.worktreeBytes ?? [:]).merging([folder.path: bytes]) { max($0, $1) } + } + } + if stats != (record.stats ?? TutorialStats()) { + record.stats = stats + self.record = record + } + } + private mutating func complete(at date: Date) { let step = record!.step record?.done.append(step) @@ -521,7 +604,9 @@ public struct TutorialProgress: Sendable { return Checkpoint( completed: viewerOpened && viewerInput ? now : nil, ticks: [tick("opened", viewerOpened), tick("input", viewerInput)]) - case "logs": return Checkpoint(detail: "Find the app output in Logs") + case "logs": + return Checkpoint( + completed: logsOpened ? now : nil, detail: "Find the app output in Logs", ticks: [tick("logs", logsOpened)]) case "agent": let recorded = logs.contains { udid != nil && $0.src == "agent" && $0.event == "agent_action" && $0.deviceId == udid diff --git a/apps/desktop/Sources/StimKit/TutorialViewerEvents.swift b/apps/desktop/Sources/StimKit/TutorialViewerEvents.swift index 24c2fbaedc..0f6c339b80 100644 --- a/apps/desktop/Sources/StimKit/TutorialViewerEvents.swift +++ b/apps/desktop/Sources/StimKit/TutorialViewerEvents.swift @@ -17,6 +17,7 @@ public final class TutorialViewerEvents: ObservableObject { public func input(_ udid: String) { append(.input(udid)) } public func actionsViewed(_ udid: String) { append(.actionsViewed(udid)) } public func replayPlayed(_ udid: String) { append(.replayPlayed(udid)) } + public func logsOpened(_ path: String) { append(.logsOpened(path)) } private func append(_ event: TutorialViewerEvent) { sequence += 1 diff --git a/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift b/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift index 3de588c52d..74b12d8e55 100644 --- a/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift +++ b/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift @@ -285,13 +285,58 @@ private func sibling(path: String = secondPath, repository: String? = "/Users/ex #expect(state("agent", in: result).state == .done) } -@Test func tutorialLogsStepWaitsForTheUserToMarkItDone() throws { +@Test func tutorialLogsCompletesOnlyWhenATutorialWorkspacesLogsAreOpened() throws { var progress = TutorialProgress() - let result = progress.update( + var input = TutorialInput( + environment: try environment(), logRecords: [try log("anything", at: afterRebuild)], + viewerEvents: [.logsOpened("/Users/example/elsewhere")], now: afterRebuild, + record: saved(at: "logs", since: afterRebuild)) + #expect(progress.update(input).currentStep == "logs") + input.viewerEvents = [.logsOpened(tourPath)] + let result = progress.update(input) + #expect(result.currentStep == "phone") + #expect(state("logs", in: result).state == .done) + #expect(state("logs", in: result).ticks.map(\.done) == [true]) +} + +private func disk(_ bytes: Double) throws -> WorkspaceDisk { + try JSONDecoder().decode(WorkspaceDisk.self, from: Data(#"{"worktreeBytes":\#(bytes)}"#.utf8)) +} + +@Test func tutorialStatsOutliveTheWorkspacesThatProducedThem() throws { + var base = try environment() + base.repository = "/Users/example/stim-tutorial" + base.disk = try disk(300) + var hit = try sibling() + hit.disk = try disk(200) + var clone = try sibling(path: "/Users/example/stim-tutorial") + clone.disk = try disk(500) + let action = try log("press", at: afterBuild, source: "agent", event: "agent_action", device: "tutorial-simulator") + var record = saved(at: "build", since: tourStart) + record.clonePath = "/Users/example/stim-tutorial" + var progress = TutorialProgress() + let live = progress.update( TutorialInput( - environment: try environment(), logRecords: [try log("anything", at: afterRebuild)], now: afterRebuild, - record: saved(at: "logs", since: afterRebuild))) - #expect(result.currentStep == "logs") + environment: base, siblings: [hit, clone], logRecords: [action, action], now: afterRebuild, record: record)) + #expect(live.currentStep == "device") + let stats = try #require(live.record.stats) + #expect(stats.firstBuild?.durationMs == 264_197) + #expect(stats.firstBuild?.cache == "none") + #expect(stats.secondBuild?.durationMs == 7_665) + #expect(stats.secondBuild?.cache == "local") + #expect(stats.savedMs == 256_532) + #expect(stats.buildsOverlapped == false) + #expect(stats.agentActions == 2) + #expect(stats.measuredBytes == 1000) + + base.disk = try disk(100) + let later = progress.update( + TutorialInput( + environment: base, siblings: [hit, clone], logRecords: [action], now: afterRebuild.addingTimeInterval(30))) + #expect(later.record.stats == stats) + + let gone = progress.update(TutorialInput(environment: nil, siblings: [], now: afterRebuild.addingTimeInterval(60))) + #expect(gone.record.stats == stats) } @Test func tutorialFinishCompletesWithArchiveWithoutIntermediateStopSnapshot() throws { diff --git a/website/docs/desktop.md b/website/docs/desktop.md index 370e9469bb..64112f0ef3 100644 --- a/website/docs/desktop.md +++ b/website/docs/desktop.md @@ -98,7 +98,7 @@ a tiny Expo app, and shows: - **Change It Again in Parallel:** while that builds, copy the step's prompt, "While that builds, make the Tap me button green in a new worktree and check it on the simulator." The next linked worktree of the clone, made after the first change step began, has its own simulator and Metro port, and its first iOS build is a cache hit. - **Live View and Control (optional):** open a tutorial simulator's live view and tap the app yourself. A glow points at the device's live view, then its screen: tap **Tap me** and watch the counter. While the live view is open, a small card in it shows the step and its ticks, **Live view opened** and **Device controlled**; the step moves on once both are ticked. - **Agent Actions and Replay (optional):** see what your agent did on the first change's simulator, then replay it. A glow points at its live view, then its Agent Actions list, then the replay's Play button. The step ticks **Agent actions viewed** and **Replay played** and stays open so you can keep watching; **Next** then records it done. When no agent actions were recorded on that simulator, the step says so. -- **App Logs (optional):** read the app's output and any errors in Logs. +- **App Logs (optional):** read the app's output and any errors in Logs. The step ticks **Logs opened** and completes when you show the Logs of either tutorial worktree, or press **Show me**, while the step is current. - **Watch on Your Phone (optional):** **Pair a Phone** opens the Pair a Phone wizard, which turns on serving itself. An existing pairing shows **Done Already**, then "Open Stim on your phone: the tutorial workspaces are there". - **Share Your Finish (optional):** a prompt you may paste before finishing, while your change still exists, to fork the tutorial repo and open a public pull request with before and after screenshots of your change, a short note on how Stim verified it, and a link to Stim. It is public, needs your agent to have GitHub access (`gh`), and a bot replies and closes it. Desktop never runs it and nothing depends on it. When Stim reports a pull request for the first change's worktree, including one from your fork, the step ticks **Pull request opened**, links it and completes; Stim checks GitHub every few minutes, so the tick can take up to five minutes. - **Finish and Archive:** the prompt names the two worktrees; your agent stops their apps and removes only those, dropping their changes (a forced removal is allowed for exactly those two, after a plain remove refuses). The clone stays. **Open Archived** opens the same workspace page as a read-only archive, with retained build history, logs and recordings. Archived sidebar rows keep the live repository/worktree grouping and app labels.