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
13 changes: 9 additions & 4 deletions apps/desktop/Sources/StimKit/TutorialSteps.swift
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,19 @@ public enum TutorialSteps {
]),
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",
ask: "Open a pull request to appandflow/stim-tutorial with my title color change, with before and after screenshots from the simulator. See stim guide tutorial share.", section: "share",
commands: [
"cd \"{tour}\"",
"git commit -am \"Tutorial change\" -m \"Build <time>, second build cache <hit or miss>\"",
"xcrun simctl io {udid} screenshot finish.png",
"git commit -am \"<one-line summary>\"",
"mkdir -p .expo/screenshots",
"git checkout origin/main -- theme.js",
"xcrun simctl io {udid} screenshot .expo/screenshots/before.png",
"git checkout HEAD -- theme.js",
"xcrun simctl io {udid} screenshot .expo/screenshots/after.png",
"cp .github/pull_request_template.md .expo/screenshots/body.md",
"gh repo fork appandflow/stim-tutorial --remote --remote-name fork",
"git push -u fork HEAD",
"gh pr create --repo appandflow/stim-tutorial --fill --attach \"finish.png#The change running in the simulator\"",
"gh pr create --repo appandflow/stim-tutorial --title \"<one-line summary>\" --body-file .expo/screenshots/body.md --attach \".expo/screenshots/before.png#Before\" --attach \".expo/screenshots/after.png#After\"",
]),
TutorialStep(
id: "finish", title: "Finish and Archive", who: "agent", optional: false,
Expand Down
6 changes: 5 additions & 1 deletion packages/stim-cli/src/__tests__/guide.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -618,14 +618,18 @@ test('tutorial restart removes nothing, so it cannot contradict the finish force
expect(flat('restart')).toMatch(/remove nothing/i);
});

test('the share step comes before finish and pushes to a fork with the simulator udid', () => {
test("the share step comes before finish, pushes to a fork with the simulator udid, and attaches the body's screenshots", () => {
const ids = TUTORIAL_STEPS.map((step) => step.id);
expect(ids.indexOf('share')).toBeLessThan(ids.indexOf('finish'));
const commands = TUTORIAL_STEPS.find((step) => step.id === 'share')!.commands.join('\n');
expect(commands).toContain('{udid}');
expect(commands).not.toContain('booted');
expect(commands).toMatch(/gh repo fork[\s\S]*git push[\s\S]*gh pr create --repo/);
expect(flat('share')).toMatch(/never booted/);
for (const shot of ['before', 'after']) {
expect(commands).toContain(`--attach ".expo/screenshots/${shot}.png`);
expect(flat('share')).toContain(`(./.expo/screenshots/${shot}.png)`);
}
});

test('the agent guide shares the Stim Desktop link the commands print, once', () => {
Expand Down
15 changes: 10 additions & 5 deletions packages/stim-cli/src/guide/tutorial-data.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
export const TUTORIAL_REPO = 'appandflow/stim-tutorial';

const TUTORIAL_BUNDLE_ID = 'dev.stim.tutorial';
export const TUTORIAL_BUNDLE_ID = 'dev.stim.tutorial';

export const TUTORIAL_RESTART_PROMPT = 'Restart the Stim tutorial.';

Expand All @@ -15,7 +15,7 @@ export const TUTORIAL_ASKS = {
"I'm done with these experiments in {base} and don't need the changes. Stop the apps and remove the worktrees {worktrees}, and keep the clone. Follow stim guide tutorial finish.",
delete:
'Remove the Stim tutorial: remove its worktrees and the clone at {base} with stim worktree remove, then delete {base}. Follow stim guide tutorial delete.',
share: `Open a pull request to ${TUTORIAL_REPO} with my title color change, and include a screenshot of it running in the simulator. See stim guide tutorial share.`,
share: `Open a pull request to ${TUTORIAL_REPO} with my title color change, with before and after screenshots from the simulator. See stim guide tutorial share.`,
retry: 'The first iOS build of the tutorial app in {tour} failed. Find out why and run it on iOS again.',
};

Expand Down Expand Up @@ -107,11 +107,16 @@ export const TUTORIAL_STEPS: {
section: 'share',
commands: [
'cd "{tour}"',
'git commit -am "Tutorial change" -m "Build <time>, second build cache <hit or miss>"',
'xcrun simctl io {udid} screenshot finish.png',
'git commit -am "<one-line summary>"',
'mkdir -p .expo/screenshots',
'git checkout origin/main -- theme.js',
'xcrun simctl io {udid} screenshot .expo/screenshots/before.png',
'git checkout HEAD -- theme.js',
'xcrun simctl io {udid} screenshot .expo/screenshots/after.png',
'cp .github/pull_request_template.md .expo/screenshots/body.md',
`gh repo fork ${TUTORIAL_REPO} --remote --remote-name fork`,
'git push -u fork HEAD',
`gh pr create --repo ${TUTORIAL_REPO} --fill --attach "finish.png#The change running in the simulator"`,
`gh pr create --repo ${TUTORIAL_REPO} --title "<one-line summary>" --body-file .expo/screenshots/body.md --attach ".expo/screenshots/before.png#Before" --attach ".expo/screenshots/after.png#After"`,
],
},
{
Expand Down
85 changes: 62 additions & 23 deletions packages/stim-cli/src/guide/tutorial.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { TUTORIAL_VERSION } from '@stim-cli/core/state';
import { TUTORIAL_REPO, TUTORIAL_RESTART_PROMPT, TUTORIAL_STEPS } from './tutorial-data.ts';
import { TUTORIAL_BUNDLE_ID, TUTORIAL_REPO, TUTORIAL_RESTART_PROMPT, TUTORIAL_STEPS } from './tutorial-data.ts';
import type { GuideTopic } from './types.ts';

const paths = `Use {base} = ~/stim-tutorial unless the user named another folder. Expand ~
Expand All @@ -12,6 +12,24 @@ even when the user's settings would place the device or the build on another
Mac. Only an explicit request to build on another Mac changes the build, with
stim ios --remote local --remote-build "<machine>"; the device stays here.`;

const screenshots = `Before and after screenshots, for a pull request: in each change's worktree,
run the app on iOS before you edit anything, open it with agent-device and save
the screen, then make the change and, once Fast Refresh applies it, save the
same screen on the same device:

mkdir -p .expo/screenshots
export AGENT_DEVICE_STATE_DIR="<agentDevice.stateDir from stim status --json>"
agent-device open ${TUTORIAL_BUNDLE_ID} --platform ios --udid <ios.udid>
agent-device screenshot .expo/screenshots/before.png
(make the change)
agent-device screenshot .expo/screenshots/after.png

Without agent-device, use xcrun simctl io <ios.udid> screenshot
.expo/screenshots/before.png, using that worktree's udid from stim status --json,
never booted. Take both with the same tool so they match in size. .expo/ is
ignored and outside the native fingerprint, so the files are never committed,
never change the build, and never block stim worktree remove. Keep each PNG under 1 MB.`;

function commands(id: string): string {
return TUTORIAL_STEPS.find((step) => step.id === id)!.commands.join('\n');
}
Expand Down Expand Up @@ -71,6 +89,8 @@ and stop.

${local}

${screenshots}

PAUSE: end the turn. Tell the user to ask for a visual change next, such as
making the title purple, in their own words. Each change runs in a new linked
worktree of {base} (stim guide agent), and its first iOS build takes a few
Expand Down Expand Up @@ -135,39 +155,58 @@ Never use --force in this step, and never delete any path other than {base}. Rep
what you removed and end the turn.`,
},
share: {
summary: 'Optionally open a public pull request with a screenshot of the change',
summary: 'Optionally open a public pull request with before and after screenshots of the change',
body: () => `SHARE YOUR FINISH (OPTIONAL)

Only on the user's explicit request, which the share prompt is, and before the
finish step removes the worktrees. The pull request is public: the user's GitHub
name and change appear on ${TUTORIAL_REPO}, and a bot replies and closes it. It
needs gh signed in. Never open it unprompted or from any other step.

Work from the worktree holding the user's change, {tour}. Commit the change
there, fork the repository and push the branch to the fork, since the user has
no write access:
Work from the worktree holding the user's change, {tour}. Commit only the
change's files there, never .expo/screenshots/. Fork the repository and push the
branch to the fork, since the user has no write access:

gh repo fork ${TUTORIAL_REPO} --remote --remote-name fork
git push -u fork HEAD

Screenshot: take a PNG under 1 MB of the app showing the change, with
agent-device screenshot when it is installed, otherwise
xcrun simctl io <ios.udid> screenshot finish.png, using the udid of that
worktree from stim status --json, never booted. If the app is no longer
running, run it again from the branch first.

Open the pull request with gh pr create --repo ${TUTORIAL_REPO} --fill. Put one
short line with the build time and whether the second worktree's first iOS build
was a cache hit, when you know them from stim status --json or stim stats, in the
commit message body (git commit -m "<title>" -m "<that line>"), so --fill carries it
into the pull request body.

Attach the screenshot with gh: gh pr create --attach "finish.png#The change
running in the simulator" uploads the image and appends it to the body. gh
2.99.0 (2026-09-01) has --attach; confirm with gh pr create --help rather than
guessing a version. When gh has no --attach, commit the PNG on the PR branch as
finish/<github-login>.png before pushing and embed it in the body with a
relative link: ![the change](finish/<github-login>.png).`,
Screenshots: use .expo/screenshots/before.png and .expo/screenshots/after.png from that
worktree (stim guide tutorial run). If either is missing, take it now on the same
device, that worktree's ios.udid from stim status --json, never booted, with the
app running from the branch (run it again first if needed). For
a missing before, show the original screen with
git checkout origin/main -- <changed files>, capture it once Fast Refresh applies,
then restore the change with git checkout HEAD -- <changed files> and capture the
after again with the same tool, so both match in size.

Body: write .expo/screenshots/body.md from the clone's
.github/pull_request_template.md, keeping its headings, table and Stim link and
dropping its <!-- --> comments. An older clone without the template gets the
same parts, in this order:
- the first line: one sentence saying what changed and why;
- the table, with ![Before](./.expo/screenshots/before.png) and
![After](./.expo/screenshots/after.png) in its cells;
- a How it was verified section, with only what you observed: Device is ios.name from
stim status --json; Readiness is the "app reported ready" time stim ios
printed; Build is lastBuilds.ios.durationMs and whether lastBuilds.ios.cacheHit
was local or remote (a cache hit) or false (a full build), plus, when you know
it, whether the second worktree's first iOS build was a cache hit; Logs is the
result of stim logs --errors. Drop a line you did not observe rather than
guess it;
- the closing line: Built and verified with [Stim](https://github.com/appandflow/stim).

Open the pull request from {tour}:

gh pr create --repo ${TUTORIAL_REPO} --title "<the one-line summary>" \\
--body-file .expo/screenshots/body.md \\
--attach ".expo/screenshots/before.png#Before" --attach ".expo/screenshots/after.png#After"

--attach uploads each image and rewrites the matching ./.expo/screenshots/ reference in
the body to the uploaded file, so the table shows both images. gh 2.99.0
(2026-09-01) has --attach; confirm with gh pr create --help rather than guessing
a version. When gh has no --attach, open the pull request with --body-file alone
and tell the user to drag the two images into the table on GitHub. Give the user
the pull request URL.`,
},
restart: {
summary: 'Start the tutorial again without removing anything',
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 runs, ask for another change, for example "Try a dark background 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, Agent Actions and Replay, App Logs (optional):** open the live view, watch what your agent did on the device and replay it, and read the logs.
- **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". **Skip** stays available.
- **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 a screenshot of your change. 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.
- **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.
- **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.
- **Delete the Test App (optional):** a prompt to remove the tutorial for good. Your agent removes any worktrees of the clone and then the clone itself with a plain `stim worktree remove`, stopping to ask if one holds changes, so their simulators, Metro ports and Stim records are torn down, and then deletes the clone's folder. The step completes when Stim no longer lists the clone and its folder is gone. Skip it to keep the clone.

Expand Down
Loading