From 1bd204b9b7de83b8d2478fb0d2d7fd2ca397ac80 Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Sat, 10 Oct 2026 15:48:50 -0400 Subject: [PATCH 1/3] feat(desktop): keep tutorial stats and complete App Logs when Logs opens TutorialRecord.stats keeps the first and second build, the agent action count and each tutorial folder's measured size after the workspaces are removed. App Logs completes when the Logs view of a tutorial workspace appears. Fixes #3377 --- .../StimDesktop/Views/TutorialPanel.swift | 1 + .../StimDesktop/Views/WorkspaceDetail.swift | 3 + .../Sources/StimKit/TutorialProgress.swift | 87 ++++++++++++++++++- .../StimKit/TutorialViewerEvents.swift | 1 + .../StimKitTests/TutorialProgressTests.swift | 45 ++++++++-- 5 files changed, 131 insertions(+), 6 deletions(-) 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..2d2ab2371c 100644 --- a/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift +++ b/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift @@ -290,6 +290,9 @@ 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 { 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..19dd82c324 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 last 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]) { $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..cf3a091b74 100644 --- a/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift +++ b/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift @@ -285,13 +285,48 @@ 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 != nil) + #expect(stats.secondBuild?.cache == "local") + #expect(stats.agentActions == 2) + #expect(stats.measuredBytes == 1000) + + let gone = progress.update(TutorialInput(environment: nil, siblings: [], now: afterRebuild.addingTimeInterval(60))) + #expect(gone.record.stats == stats) } @Test func tutorialFinishCompletesWithArchiveWithoutIntermediateStopSnapshot() throws { From 387489a0a1f80e925586ebc80d90b0b672f5d4bf Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Sat, 10 Oct 2026 15:49:10 -0400 Subject: [PATCH 2/3] docs: App Logs completes when the tutorial's Logs open --- website/docs/desktop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/desktop.md b/website/docs/desktop.md index 370e9469bb..892a1b182d 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 the Logs view of either tutorial worktree appears. - **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. From f14904b891b140717ed191ffe14e8e9e4c0e05e6 Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Sat, 10 Oct 2026 15:53:24 -0400 Subject: [PATCH 3/3] fix(desktop): count App Logs only when Logs open during the step --- .../desktop/Sources/StimDesktop/Views/RootView.swift | 1 + .../Sources/StimDesktop/Views/WorkspaceDetail.swift | 4 +++- apps/desktop/Sources/StimKit/TutorialProgress.swift | 4 ++-- .../Tests/StimKitTests/TutorialProgressTests.swift | 12 +++++++++++- website/docs/desktop.md | 2 +- 5 files changed, 18 insertions(+), 5 deletions(-) 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/WorkspaceDetail.swift b/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift index 2d2ab2371c..c158e540dc 100644 --- a/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift +++ b/apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift @@ -291,7 +291,9 @@ struct WorkspaceDetail: View { ) .tutorialAnchor(.logsTab, workspace: workspace.path) .task(id: archive == nil ? (page.isUnified ? logsApp : workspace).path : nil) { - if archive == nil { TutorialViewerEvents.shared.logsOpened((page.isUnified ? logsApp : workspace).path) } + 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 19dd82c324..6ca536832f 100644 --- a/apps/desktop/Sources/StimKit/TutorialProgress.swift +++ b/apps/desktop/Sources/StimKit/TutorialProgress.swift @@ -109,7 +109,7 @@ public struct TutorialStats: Codable, Equatable, Sendable { public var firstBuild: Build? public var secondBuild: Build? public var agentActions: Int? - /// The last measured size of each tutorial folder, keyed by path: both worktrees and the clone. + /// The largest measured size of each tutorial folder, keyed by path: both worktrees and the clone. public var worktreeBytes: [String: Double]? public init() {} @@ -493,7 +493,7 @@ public struct TutorialProgress: Sendable { 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]) { $1 } + stats.worktreeBytes = (stats.worktreeBytes ?? [:]).merging([folder.path: bytes]) { max($0, $1) } } } if stats != (record.stats ?? TutorialStats()) { diff --git a/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift b/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift index cf3a091b74..74b12d8e55 100644 --- a/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift +++ b/apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift @@ -320,11 +320,21 @@ private func disk(_ bytes: Double) throws -> WorkspaceDisk { 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 != nil) + #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) } diff --git a/website/docs/desktop.md b/website/docs/desktop.md index 892a1b182d..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. The step ticks **Logs opened** and completes when the Logs view of either tutorial worktree appears. +- **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.