Nothing imports from vendor/ at runtime — the forks are consumed as published npm packages (vendor/README.md is explicit). Forcing the submodule init in bootstrap taught every fresh worktree a false dependency. --forks remains for deliberately developing a fork.
Unified · Split
| @@ -3,11 +3,13 @@ · 2 unmodified lines | |||
| 3 | ## Fresh Checkout / Worktree Setup | 3 | ## Fresh Checkout / Worktree Setup |
| 4 | 4 | ||
| 5 | Run `bun run bootstrap` first in any fresh checkout or worktree. It is | 5 | Run `bun run bootstrap` first in any fresh checkout or worktree. It is |
| 6 | idempotent: inits the vendor submodules (`vendor/emulate`, `vendor/mcporter` — | 6 | idempotent: runs `bun install` (whose prepare hook builds the internal |
| 7 | the e2e suite needs both), runs `bun install` (whose prepare hook builds the | 7 | packages dev servers fail without) and installs Playwright chromium. |
| 8 | internal packages dev servers fail without), and installs Playwright chromium. | ||
| 9 | Skipping it is why fresh worktrees die with "Failed to resolve entry for | 8 | Skipping it is why fresh worktrees die with "Failed to resolve entry for |
| 10 | package '@executor-js/vite-plugin'". | 9 | package '@executor-js/vite-plugin'". The `vendor/` submodules are NOT |
| 10 | needed — nothing imports from `vendor/` at runtime; those forks are consumed | ||
| 11 | from npm (see `vendor/README.md`). `bun run bootstrap --forks` inits them | ||
| 12 | only when you're deliberately developing a fork. | ||
| 11 | 13 | ||
| 12 | ## Environment Gotchas (learned the hard way) | 14 | ## Environment Gotchas (learned the hard way) |
| 13 | 15 | ||
| @@ -1,7 +1,12 @@ | |||
| 1 | // One-command setup for a fresh checkout or agent worktree: submodules, | 1 | // One-command setup for a fresh checkout or agent worktree: dependencies |
| 2 | // dependencies (whose prepare hook builds the internal packages dev servers | 2 | // (whose prepare hook builds the internal packages dev servers need) and the |
| 3 | // need), and the Playwright browser the e2e suite drives. Idempotent and | 3 | // Playwright browser the e2e suite drives. Idempotent and safe to re-run; |
| 4 | // safe to re-run; each step prints what it is doing. | 4 | // each step prints what it is doing. |
| 5 | // | ||
| 6 | // The vendor/ submodules are intentionally NOT initialized: nothing imports | ||
| 7 | // from vendor/ at runtime — those forks are consumed as published npm | ||
| 8 | // packages (see vendor/README.md). Pass --forks only when deliberately | ||
| 9 | // developing a fork. | ||
| 5 | import { execFileSync } from "node:child_process"; | 10 | import { execFileSync } from "node:child_process"; |
| 6 | import { existsSync } from "node:fs"; | 11 | import { existsSync } from "node:fs"; |
| 7 | import { resolve } from "node:path"; | 12 | import { resolve } from "node:path"; |
| @@ -14,7 +19,9 @@ const run = (label: string, cmd: string, args: ReadonlyArray<string>) => { · 6 unmodified lines | |||
| 14 | execFileSync(cmd, [...args], { cwd: repoRoot, stdio: "inherit" }); | 19 | execFileSync(cmd, [...args], { cwd: repoRoot, stdio: "inherit" }); |
| 15 | }; | 20 | }; |
| 16 | 21 | ||
| 17 | run("vendor submodules", "git", ["submodule", "update", "--init", "--recursive"]); | 22 | if (process.argv.includes("--forks")) { |
| 23 | run("vendor fork submodules", "git", ["submodule", "update", "--init", "--recursive"]); | ||
| 24 | } | ||
| 18 | 25 | ||
| 19 | // `bun install` runs the workspace prepare hook, which builds | 26 | // `bun install` runs the workspace prepare hook, which builds |
| 20 | // @executor-js/vite-plugin and @executor-js/react — the two artifacts the | 27 | // @executor-js/vite-plugin and @executor-js/react — the two artifacts the |