also looking at this
Brief agents on the environment a fresh checkout cannot infer
#319
4 files
+126
-0
| @@ -4,6 +4,43 @@ | ||
| 4 | 4 | |
| 5 | 5 | A lightweight, high-performance cross-platform application framework built with Zig. It creates native desktop apps (macOS, Linux, Windows), mobile apps (iOS, Android), and menubar/system tray apps using web technologies. It includes a library of native UI components, advanced GPU rendering (Vulkan/Metal/Direct3D), WebSocket support, a JavaScript bridge, system integration (notifications, clipboard, file dialogs), and a TypeScript SDK (`craft-native`) for building apps without writing Zig directly. Reproducible binary-size and startup benchmarks live in [`benchmarks/`](./benchmarks). |
| 6 | 6 | |
| 7 | ## Environment | |
| 8 | ||
| 9 | These are the things a fresh checkout cannot tell you, each of which has already cost a separately diagnosed build failure. None is a code defect. | |
| 10 | ||
| 11 | **`zig build` needs the pinned toolchain.** The `zig` on your PATH is almost certainly the wrong snapshot, and the build refuses it by design. Point `CRAFT_ZIG` at the executable `pantry.lock` pins, or activate the pinned Pantry toolchain. `CRAFT_ALLOW_UNPINNED_ZIG=1` exists only for deliberately testing another snapshot. | |
| 12 | ||
| 13 | **`zig build` also needs three sibling checkouts outside the repository.** `packages/zig/build.zig.zon` resolves them by relative path — `../../../../Libraries/zig-js` and likewise `zig-regex` and `zig-gc` — so they must sit four levels above `packages/zig`, beside the repository's own parent. CI provides them through `.github/actions/first-party-zig-deps`, which clones each at the SHA in `pins.env`. | |
| 14 | ||
| 15 | Two traps follow from that. The pins are **not branch tips**, so `git fetch` and `git pull` will not reach them; fetch the commit directly (`git fetch --depth 1 origin <sha>`), which is what the action does and why it says so. And a checkout that merely *exists* is not enough: a local clone at a different revision fails to compile against the pinned Zig with errors that look like Zig bugs. | |
| 16 | ||
| 17 | **A container that installs Zig still cannot build** until both of the above are satisfied. If you cannot satisfy them, say so and let CI's `zig-core` job be the signal rather than fighting it. | |
| 18 | ||
| 19 | **`bun run test` is the Zig suite, not the SDK suite.** The SDK suite is `bun run test:sdk`. A bare `bun test` at the repository root is worse than either: `bunfig.toml` picks up vendored fixtures under `pantry/`, so it reports failures that have nothing to do with your change. Inside a package, plain `bun test` is correct. | |
| 20 | ||
| 21 | **Not every Zig test runs on every runner.** Zig collects tests only from files its lazy analysis reaches, and `src/ios.zig` is skipped off Darwin. The whole of `bridge_error.zig` and every `bridge_mobile_*.zig` module is therefore invisible to the Linux leg of `zig-core`. For iOS bridge work, read the **macos-latest** leg; a green Linux leg means almost nothing. | |
| 22 | ||
| 23 | **A new `scripts/*.test.ts` file does not run until `ci.yml` names it.** The lint job invokes those tests file by file, so a test added to `scripts/` and nowhere else is silently never executed. Add the invocation in the same change. | |
| 24 | ||
| 25 | **`main` is not branch-protected.** There are no required status checks, so a red pull request *can* be merged. Never merge one. | |
| 26 | ||
| 27 | ## Verification | |
| 28 | ||
| 29 | Before pushing, run what your machine can actually run: | |
| 30 | ||
| 31 | ```sh | |
| 32 | bun run test:sdk # the SDK suite | |
| 33 | bun run typecheck | |
| 34 | bun run verify:packages # needs the package dists built first | |
| 35 | bunx --bun pickier . # never eslint; 0 errors is the bar | |
| 36 | ``` | |
| 37 | ||
| 38 | `verify:packages` fails on a fresh checkout until the public packages are built, which is why CI runs it after the builds rather than before. | |
| 39 | ||
| 40 | A pull request touching `packages/ios/**`, `packages/android/**` or the mobile Zig bridges also boots a real simulator or emulator on a long job. When that job is red for a reason unrelated to your change, say so on the pull request instead of thrashing on it. | |
| 41 | ||
| 42 | `mobile-e2e.yml` installs with `--frozen-lockfile` while `ci.yml` does not, so a dependency edit without a regenerated `bun.lock` passes one workflow and fails the other. | |
| 43 | ||
| 7 | 44 | ## Linting |
| 8 | 45 | |
| 9 | 46 | - Use **pickier** for linting — never use eslint directly |
| @@ -21,6 +58,7 @@ A lightweight, high-performance cross-platform application framework built with | ||
| 21 | 58 | - **buddy-bot** handles dependency updates — not renovatebot |
| 22 | 59 | - **better-dx** provides shared dev tooling as peer dependencies — do not install its peers (e.g., `typescript`, `pickier`, `bun-plugin-dtsx`) separately if `better-dx` is already in `package.json` |
| 23 | 60 | - If `better-dx` is in `package.json`, ensure `bunfig.toml` includes `linker = "hoisted"` |
| 61 | - Do not run `bun audit fix` unreviewed. It is willing to *downgrade* a package to fall below an advisory window rather than upgrade past it, and it reports that as a fix. | |
| 24 | 62 | |
| 25 | 63 | ## Distribution |
| 26 | 64 | |
| @@ -28,7 +66,10 @@ A lightweight, high-performance cross-platform application framework built with | ||
| 28 | 66 | - The `release.yml` workflow publishes to pantry on every tag via `home-lang/pantry/packages/action@main` with `publish: 'zig'`. |
| 29 | 67 | - Tests / monorepo dev loop: set `CRAFT_BIN=/absolute/path/to/craft` to override the PATH lookup. The SDK's `AppConfig.craftPath` field accepts the same kind of override at app-config time. |
| 30 | 68 | - Adding new lookup paths or fallbacks to `binary-resolver.ts` defeats the pantry contract — don't. |
| 69 | - Release archives are built natively, one runner per platform. They are not cross-compiled, so a full release cannot be rehearsed on one machine. | |
| 31 | 70 | |
| 32 | 71 | ## Commits |
| 33 | 72 | |
| 34 | 73 | - Use conventional commit messages (e.g., `fix:`, `feat:`, `chore:`) |
| 74 | - Keep commits small and focused: 3–5 files each | |
| 75 | - Do not add agent attribution trailers to commits or pull requests | |