Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions apps/desktop/Sources/StimDesktop/Views/RootView.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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) }
}
})
}
Expand Down
1 change: 1 addition & 0 deletions apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
Expand Down
5 changes: 5 additions & 0 deletions apps/desktop/Sources/StimDesktop/Views/WorkspaceDetail.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}
}
Expand Down
87 changes: 86 additions & 1 deletion apps/desktop/Sources/StimKit/TutorialProgress.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand All @@ -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
Expand Down Expand Up @@ -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 {
Expand All @@ -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",
Expand Down Expand Up @@ -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<String> = []
Expand Down Expand Up @@ -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
}
}
Expand Down Expand Up @@ -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 =
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions apps/desktop/Sources/StimKit/TutorialViewerEvents.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 50 additions & 5 deletions apps/desktop/Tests/StimKitTests/TutorialProgressTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion website/docs/desktop.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading