From c9630bcd0c5435446f55aae52c165df820013fd4 Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Sun, 6 Sep 2026 21:37:22 -0400 Subject: [PATCH] docs: require warm completion before starting the app --- packages/stim-cli/src/__tests__/guide.test.ts | 5 ++++- packages/stim-cli/src/guide/agent.ts | 6 ++++++ packages/stim-cli/src/guide/lifecycle.ts | 5 +++++ 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/packages/stim-cli/src/__tests__/guide.test.ts b/packages/stim-cli/src/__tests__/guide.test.ts index 356f7b35..9430115c 100644 --- a/packages/stim-cli/src/__tests__/guide.test.ts +++ b/packages/stim-cli/src/__tests__/guide.test.ts @@ -219,11 +219,14 @@ test('the errors topic documents every code the build commands and the iOS signi } }); -test('current guides expose warm and remove while leaving worktree creation to Git', () => { +test('current guides require completed warming and leave worktree creation to Git', () => { const body = allBodies().join('\n'); expect(body).toContain('git worktree add'); expect(body).toContain('stim worktree warm'); expect(body).toContain('stim worktree remove'); + for (const guide of [renderTopic('agent'), renderSection('lifecycle', 'options')]) { + expect(guide).toContain('Wait for warm to exit successfully (exit code 0)'); + } expect(body).not.toMatch(/worktree create|--carry-ignored|STIM_WORKTREE_BRANCH_EXISTS/); expect(body).not.toMatch(/worktreeDir|worktree\.baseRef|worktree\.include|\.worktreeinclude/); expect(sectionLookup('errors')['STIM_WORKTREE_BRANCH_EXISTS']).toBeUndefined(); diff --git a/packages/stim-cli/src/guide/agent.ts b/packages/stim-cli/src/guide/agent.ts index 9de8d79f..50fa11d3 100644 --- a/packages/stim-cli/src/guide/agent.ts +++ b/packages/stim-cli/src/guide/agent.ts @@ -18,6 +18,12 @@ configuration files. It preserves the branch, tracked files, and every existing destination entry; existing ignored directories are skipped whole, not filled in. Read guide lifecycle options for exclusions and incomplete-copy remedies. +Wait for warm to exit successfully (exit code 0) before running stim start, +stim ios, stim android, or a dependency install in that worktree. If the shell +tool returns a running session or job ID, poll or wait for that job to finish; +the ID is not completion. Do not install dependencies while warm is copying. +If warm fails or reports incomplete, resolve the reported failure first. + Before native worktree work, run doctor for the platform in scope. It checks the main checkout from a linked worktree. Fix relevant findings and inspect the upstream gap. It also prints the running CLI version and the stim installation diff --git a/packages/stim-cli/src/guide/lifecycle.ts b/packages/stim-cli/src/guide/lifecycle.ts index fc6777d6..d967bff7 100644 --- a/packages/stim-cli/src/guide/lifecycle.ts +++ b/packages/stim-cli/src/guide/lifecycle.ts @@ -604,6 +604,11 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT) worktrees of the same Git repository; the main checkout must be available. Running it in the main checkout refuses. + Wait for warm to exit successfully (exit code 0) before running start, + ios, android, or a dependency install in that worktree. If a shell tool + yields a running session or job ID, poll or wait for completion; empty + stdout or a returned job ID does not mean the copy has finished. + Warm copies installed dependencies, Pods, native output, and other ignored paths eligible under the main checkout's Git ignore rules, including .env and local configuration. The source's nonempty