From e0ee1e85c260d46c670544f942313010a06505c3 Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Sat, 10 Oct 2026 13:24:32 -0400 Subject: [PATCH 01/10] feat(desktop): drop the tutorial's commands disclosure Refs #3366 --- apps/desktop/README.md | 13 ++-- .../Sources/StimDesktop/TutorialModel.swift | 7 -- .../Sources/StimDesktop/Views/RootView.swift | 2 +- .../StimDesktop/Views/TutorialPanel.swift | 38 +--------- .../Sources/StimKit/TutorialCommands.swift | 46 +++--------- .../Sources/StimKit/TutorialSteps.swift | 74 +++---------------- .../StimKitTests/TutorialCommandsTests.swift | 24 ------ .../TutorialScreenshotTests.swift | 27 +------ apps/desktop/scripts/generate-tokens.mjs | 6 +- website/docs/desktop.md | 11 +-- 10 files changed, 34 insertions(+), 214 deletions(-) diff --git a/apps/desktop/README.md b/apps/desktop/README.md index 6da1e24039..6a13748d49 100644 --- a/apps/desktop/README.md +++ b/apps/desktop/README.md @@ -1834,12 +1834,12 @@ To check a bundle, point the DSN at a local listener, such as `http://@127. **Help > Stim Tutorial…** and the setup guide's **Take the Tutorial** button open an inspector-width trailing column. It replaces the inspector until closed; Cmd-Opt-I returns to the inspector. A new tutorial path opens it once, after open -sheets close. UserDefaults stores progress, skipped steps and whether the Commands section is open. +sheets close. UserDefaults stores progress and skipped steps. Unfinished tours resume at launch when status lists the tracked path; archived ones show Done. Closing preserves progress. Restart shows the agent prompt and resets progress at once; see below for which worktrees count afterwards. The three-minute workspace warning starts at the first Copy of the run prompt -and survives relaunch. Copying commands does not start it. Only archives +and survives relaunch. Only archives removed after this run started can complete the tutorial. The panel clones appandflow/stim-tutorial and follows: a tutorial workspace @@ -1869,12 +1869,9 @@ Mac" check. Completed optional steps stay expanded so their handoff remains visible. The tutorial never starts the server or pairs or grants access. Mark done appears after two minutes. -Each step with a prompt shows it first, then a collapsed "Commands your agent will run" -section; whether it is open is a per-user `tutorial.commandsExpanded` preference. The prompts and the -short command lists come from `TUTORIAL_ASKS` and each step's `commands` in -`tutorial-data.ts`, with the tracked paths, the agent-device state directory and the -simulator UDID substituted; the guide's own `manual` lists are unchanged. Create the -Tutorial has no commands. Desktop never runs the commands. Make a Change has a Run iOS button that calls the same `ActionCenter.runApp` as the +A step with a prompt shows it with a Copy button. The prompts come from `TUTORIAL_ASKS` in +`tutorial-data.ts`, with the tracked paths substituted. The steps' command lists there feed only +`stim guide tutorial manual`; Desktop does not show them. Make a Change has a Run iOS button that calls the same `ActionCenter.runApp` as the Build section's Run, and is disabled while a build or action runs in the workspace. The panel cannot see a removal refusal from an agent-run command: the finish step keeps showing the finish prompt. Check the agent's output and revert the diff --git a/apps/desktop/Sources/StimDesktop/TutorialModel.swift b/apps/desktop/Sources/StimDesktop/TutorialModel.swift index 0d94014611..6f12a4cfd7 100644 --- a/apps/desktop/Sources/StimDesktop/TutorialModel.swift +++ b/apps/desktop/Sources/StimDesktop/TutorialModel.swift @@ -197,13 +197,6 @@ final class TutorialModel: ObservableObject { refresh(now: now) } - func commands(for step: TutorialStep) -> String { - tutorialCommands( - step.commands, tourPath: tourPath, repository: workspace?.worktree?.repository ?? snapshot?.record.clonePath, - stateDir: workspace?.agentDevice?.stateDir, - udid: workspace?.ios?.udid, second: snapshot?.record.secondPath) - } - private func refresh(now: Date = Date()) { guard statusLoaded else { return } update( diff --git a/apps/desktop/Sources/StimDesktop/Views/RootView.swift b/apps/desktop/Sources/StimDesktop/Views/RootView.swift index 38c853189b..2b3eab21e5 100644 --- a/apps/desktop/Sources/StimDesktop/Views/RootView.swift +++ b/apps/desktop/Sources/StimDesktop/Views/RootView.swift @@ -127,7 +127,7 @@ struct RootView: View { issues: tutorial.workspace?.issues ?? [], phoneState: tutorial.phoneState, canRunIOS: tutorial.workspace.map { $0.build?.isRunning != true && actions.active(for: $0.path) == nil } ?? false, agentDeviceMissing: tutorial.workspace?.agentDevice?.installed == false, - asks: tutorial.ask, commands: tutorial.commands, + asks: tutorial.ask, copied: { tutorial.copiedPrompt() }, skip: tutorial.skip, markDone: tutorial.markDone, restart: { tutorial.open(beginning: true) }, runIOS: { diff --git a/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift b/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift index 53e9026938..555b24c3a2 100644 --- a/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift +++ b/apps/desktop/Sources/StimDesktop/Views/TutorialPanel.swift @@ -13,7 +13,6 @@ struct TutorialPanel: View { var canRunIOS = false var agentDeviceMissing = false var asks: (TutorialStep) -> String? = { $0.ask } - var commands: (TutorialStep) -> String var copied: () -> Void = {} var skip: () -> Void = {} var markDone: () -> Void = {} @@ -25,7 +24,6 @@ struct TutorialPanel: View { var updateCLI: () -> Void = {} @State private var expanded: String? @State private var collapsedOptional: Set = [] - @AppStorage("tutorial.commandsExpanded") private var commandsExpanded = false @ObservedObject private var updater = AppUpdater.shared @ObservedObject private var flags = FeatureFlagStore.shared private var steps: [TutorialStep] { TutorialSteps.steps(phoneApp: flags.phoneApp) } @@ -131,7 +129,7 @@ struct TutorialPanel: View { if open { VStack(alignment: .leading, spacing: Space.md) { Text(explanation(step.id)).foregroundStyle(Palette.secondary) - copyBlock(step) + if let ask = asks(step) { TutorialPromptBox(prompt: ask, onCopy: copied) } if step.id == "build", agentDeviceMissing { AgentDeviceCard(copied: copied) } if step.id == "phone", snapshot.record.phonePairedAtStart == true { Text(phoneState.buttonTitle).font(.stim(.footnote)).foregroundStyle(Palette.success) @@ -201,40 +199,6 @@ struct TutorialPanel: View { } } - @ViewBuilder private func copyBlock(_ step: TutorialStep) -> some View { - let ask = asks(step) - let hasCommands = !step.commands.isEmpty - let showsAsk = ask != nil - if let ask, showsAsk { - TutorialPromptBox(prompt: ask, onCopy: copied) - } - if hasCommands { - DisclosureGroup(isExpanded: $commandsExpanded) { - VStack(alignment: .leading, spacing: Space.sm) { - Text(showsAsk ? "Your agent runs these. You can also run them yourself." : "Run these yourself.") - .font(.stim(.footnote)).foregroundStyle(Palette.secondary) - commandBlock(step) - } - .padding(.top, Space.sm) - } label: { - Text(showsAsk ? "Commands your agent will run" : "Commands to run yourself") - .font(.stim(.footnote)).foregroundStyle(Palette.secondary) - } - .accessibilityLabel("Commands for \(step.title)") - } - } - - @ViewBuilder private func commandBlock(_ step: TutorialStep) -> some View { - if rendersStatic { - CommandBlock(commandText: commands(step)) - .fixedSize(horizontal: false, vertical: true) - .frame(height: 280, alignment: .top).clipped() - } else { - ScrollView { CommandBlock(commandText: commands(step)) } - .frame(maxHeight: 280) - } - } - private var footer: some View { HStack { if !snapshot.isComplete { diff --git a/apps/desktop/Sources/StimKit/TutorialCommands.swift b/apps/desktop/Sources/StimKit/TutorialCommands.swift index de706efaa7..b02ee5d7e0 100644 --- a/apps/desktop/Sources/StimKit/TutorialCommands.swift +++ b/apps/desktop/Sources/StimKit/TutorialCommands.swift @@ -1,19 +1,5 @@ import Foundation -public func tutorialCommands( - _ lines: [String], tourPath: String?, repository: String?, stateDir: String?, udid: String? = nil, - second: String? = nil -) -> String { - let base = repository ?? "~/stim-tutorial" - return fillTutorial( - lines.joined(separator: "\n"), - [ - "base": base, "tour": tourPath ?? "", - "stateDir": stateDir ?? "", - "udid": udid ?? "", "second": second ?? "", - ], shellDoubleQuotedValue) -} - public func tutorialAsk( _ template: String, tourPath: String?, repository: String?, second: String? = nil, existing: Set? = nil @@ -21,30 +7,16 @@ public func tutorialAsk( let base = repository ?? "~/stim-tutorial" let worktrees = [tourPath, second].compactMap { $0 }.filter { existing?.contains($0) ?? true } .joined(separator: " and ") - return fillTutorial( - template, - [ - "base": base, "tour": tourPath ?? "the first worktree", - "worktrees": worktrees.isEmpty ? "(there are none, so there is nothing to remove)" : worktrees, - ], { $0 }) -} - -private func fillTutorial(_ source: String, _ values: [String: String], _ format: (String) -> String) -> String { - let pattern = try! NSRegularExpression(pattern: #"\{(base|tour|second|worktrees|stateDir|udid)\}"#) - var result = source - for match in pattern.matches(in: source, range: NSRange(source.startIndex..., in: source)).reversed() { - let key = String(source[Range(match.range(at: 1), in: source)!]) + let values = [ + "base": base, "tour": tourPath ?? "the first worktree", + "worktrees": worktrees.isEmpty ? "(there are none, so there is nothing to remove)" : worktrees, + ] + let pattern = try! NSRegularExpression(pattern: #"\{(base|tour|worktrees)\}"#) + var result = template + for match in pattern.matches(in: template, range: NSRange(template.startIndex..., in: template)).reversed() { + let key = String(template[Range(match.range(at: 1), in: template)!]) guard let value = values[key] else { continue } - result.replaceSubrange(Range(match.range, in: result)!, with: format(value)) + result.replaceSubrange(Range(match.range, in: result)!, with: value) } return result } - -private func shellDoubleQuotedValue(_ value: String) -> String { - let literal = value.hasPrefix("~/") ? String(value.dropFirst(2)) : value - let escaped = literal.replacingOccurrences(of: "\\", with: "\\\\") - .replacingOccurrences(of: "\"", with: "\\\"") - .replacingOccurrences(of: "$", with: "\\$") - .replacingOccurrences(of: "`", with: "\\`") - return value.hasPrefix("~/") ? "$HOME/" + escaped : escaped -} diff --git a/apps/desktop/Sources/StimKit/TutorialSteps.swift b/apps/desktop/Sources/StimKit/TutorialSteps.swift index 9888abdc84..9fa3dcfcab 100644 --- a/apps/desktop/Sources/StimKit/TutorialSteps.swift +++ b/apps/desktop/Sources/StimKit/TutorialSteps.swift @@ -8,7 +8,6 @@ public struct TutorialStep: Sendable { public let optional: Bool public let ask: String? public let section: String? - public let commands: [String] } public enum TutorialSteps { @@ -17,86 +16,33 @@ public enum TutorialSteps { public static let all: [TutorialStep] = [ TutorialStep( id: "begin", title: "Get the Test App", who: "agent", optional: false, - ask: "Clone appandflow/stim-tutorial into {base} and follow stim guide tutorial run.", section: "run", - commands: [ - - ]), + ask: "Clone appandflow/stim-tutorial into {base} and follow stim guide tutorial run.", section: "run"), TutorialStep( id: "build", title: "Make a Change", who: "you", optional: false, - ask: nil, section: nil, - commands: [ - - ]), + ask: nil, section: nil), TutorialStep( id: "parallel", title: "Change It Again in Parallel", who: "you", optional: false, - ask: nil, section: nil, - commands: [ - - ]), + ask: nil, section: nil), TutorialStep( id: "device", title: "Live View and Control", who: "you", optional: true, - ask: nil, section: nil, - commands: [ - "stim status" - ]), + ask: nil, section: nil), TutorialStep( id: "agent", title: "Agent Actions and Replay", who: "agent", optional: true, - ask: "Open the app on the iOS simulator, take a screenshot and confirm the title color.", section: nil, - commands: [ - "cd \"{tour}\"", - "export AGENT_DEVICE_STATE_DIR=\"{stateDir}\"", - "agent-device open dev.stim.tutorial --platform ios --udid {udid}", - "agent-device screenshot tutorial.png", - "agent-device close", - "stim logs --source agent --tail 10", - ]), + ask: "Open the app on the iOS simulator, take a screenshot and confirm the title color.", section: nil), TutorialStep( id: "logs", title: "App Logs", who: "you", optional: true, - ask: nil, section: nil, - commands: [ - "stim logs --errors", - "stim logs --grep stim:tutorial", - ]), + ask: nil, section: nil), TutorialStep( id: "phone", title: "Watch on Your Phone", who: "you", optional: true, - ask: nil, section: nil, - commands: [ - - ]), + ask: nil, section: nil), TutorialStep( id: "share", title: "Share Your Finish", who: "you", optional: true, - ask: "Open a pull request to appandflow/stim-tutorial with my title color change, and include a screenshot of it running in the simulator. See stim guide tutorial share.", section: "share", - commands: [ - "cd \"{tour}\"", - "git commit -am \"Tutorial change\" -m \"Build