bun-win32 Skill
Win32 FFI binding development lifecycle for the bun-win32 monorepo.
Repository Context
WORKING_DIR (repo root = ../.. from this skill directory)
packages/ 117 @bun-win32/* binding packages
scripts/ repo automation scripts
PROMPT.md authoritative playbook (FFI rules, nullability, audits)
AGENTS.md operating rules — read before touching bindings
This skill dir: skill/bun-win32/
SKILL.md ← you are here
scripts/ automation scripts (run from WORKING_DIR)
references/ AGENTS.md, ai-core.md, ai-all.md
WORKING_DIR is the repo root. All commands run from there. Scripts in
scripts/ use ROOT = join(import.meta.dir, '../..') so they resolve
correctly when executed from this skill directory.
Lifecycle Commands (run from WORKING_DIR)
# 1. Check prerequisites (platform Windows, Bun ≥1.3.0, ripgrep, SDK, dumpbin)
bun run skill/bun-win32/scripts/doctor.ts
# 2. Full pipeline: doctor → scaffold → install → catalog → ffi-runtime → stub
bun run skill/bun-win32/scripts/bootstrap.ts {name} [--class=ClassName] [--rg=<path>] [--dll=<path>]
# 3. Individual steps
bun run skill/bun-win32/scripts/catalog.ts {name} --json # DLL∩SDK symbols
bun run skill/bun-win32/scripts/ffi-runtime.ts {name} # FFI return shapes
bun run skill/bun-win32/scripts/stub.ts {name} [--class=C] # paste-ready stubs
# 4. Auditing (run after writing bindings)
bun run skill/bun-win32/scripts/audit.ts {name} # FFI↔TS↔header consistency (--all, --fix)
bun run skill/bun-win32/scripts/nullcheck.ts {name} # SAL nullability (--all, --fix, --strict)
bunx tsc --noEmit # type-check the package
Release
rm bun.lock && bun install
bun run skill/bun-win32/scripts/preflight.ts
bun run skill/bun-win32/scripts/nullcheck.ts --all && bun run skill/bun-win32/scripts/audit.ts --all
cd packages/{name} && bun publish --access public --otp <code>
Scripts Reference
| Script |
What it does |
scripts/doctor.ts |
Prerequisites checker |
scripts/bootstrap.ts |
Orchestrated full pipeline |
scripts/catalog.ts |
dumpbin exports ∩ SDK headers → JSON |
scripts/scaffold.ts |
Template → package skeleton |
scripts/ffi-runtime.ts |
Probe FFI return-value shapes |
scripts/stub.ts |
catalog JSON → Symbols + method stubs |
scripts/audit.ts |
FFI↔TS↔header consistency auditor |
scripts/nullcheck.ts |
SAL-driven nullability auditor |
scripts/preflight.ts |
Lockfile staleness gate |
FFI Type Quick Reference
| Win32 type |
FFI |
TS |
HANDLE, HWND, HKEY, HMODULE… |
FFIType.u64 |
bigint |
SIZE_T, *_PTR, LPARAM, LRESULT, WPARAM |
FFIType.u64 |
bigint |
LARGE_INTEGER, ULARGE_INTEGER |
FFIType.i64 / u64 |
bigint |
DWORD, UINT, BOOL, HRESULT, INT, LONG, WORD, BYTE |
FFIType.u32 / i32 |
number |
LPVOID, LPCWSTR, LPSTR, LPDWORD, LPBYTE… |
FFIType.ptr |
Pointer |
void |
FFIType.void |
void |
Decision rule: Does the caller pass .ptr from a Buffer/TypedArray they allocated? Yes → ptr. No → u64.
NULL: u64 → 0n, ptr → null, u32 → 0.
Key Files
references/agents.md — full AGENTS.md (binding rules, toolchain, FFI rules, prohibitions)references/ai-core.md — @bun-win32/core contract (Win32 base class, .ptr extension, types)references/ai-all.md — @bun-win32/all contract (re-export aggregator, when to use)PROMPT.md at WORKING_DIR — deep playbook for FFI mapping, nullability, audits
Prohibited
- Bind exports not confirmed by
dumpbin //EXPORTS
- Guess types/nullability — always verify vs SDK header + MS Learn
- Use
as any / forced casts — fix the FFI mapping instead
- Reformat untouched files
- Ship without running
audit.ts --all and nullcheck.ts --all (zero findings required)
1---2name: bun-win323description: Win32 FFI binding lifecycle for @bun-win32/* packages (Win32 DLL bindings via bun:ffi on Windows). Use when generating a new package from a DLL, auditing FFI↔TS↔header consistency, fixing nullability (| NULL / | 0n), or understanding the bootstrap→catalog→stub→audit→nullcheck pipeline. Covers 117 packages; strict TypeScript; Bun runtime; Biome formatting.4---56# bun-win32 Skill78Win32 FFI binding development lifecycle for the `bun-win32` monorepo.910## Repository Context1112```13WORKING_DIR (repo root = ../.. from this skill directory)14 packages/ 117 @bun-win32/* binding packages15 scripts/ repo automation scripts16 PROMPT.md authoritative playbook (FFI rules, nullability, audits)17 AGENTS.md operating rules — read before touching bindings1819This skill dir: skill/bun-win32/20 SKILL.md ← you are here21 scripts/ automation scripts (run from WORKING_DIR)22 references/ AGENTS.md, ai-core.md, ai-all.md23```2425**WORKING_DIR is the repo root.** All commands run from there. Scripts in26`scripts/` use `ROOT = join(import.meta.dir, '../..')` so they resolve27correctly when executed from this skill directory.2829## Lifecycle Commands (run from WORKING_DIR)3031```bash32# 1. Check prerequisites (platform Windows, Bun ≥1.3.0, ripgrep, SDK, dumpbin)33bun run skill/bun-win32/scripts/doctor.ts3435# 2. Full pipeline: doctor → scaffold → install → catalog → ffi-runtime → stub36bun run skill/bun-win32/scripts/bootstrap.ts {name} [--class=ClassName] [--rg=<path>] [--dll=<path>]3738# 3. Individual steps39bun run skill/bun-win32/scripts/catalog.ts {name} --json # DLL∩SDK symbols40bun run skill/bun-win32/scripts/ffi-runtime.ts {name} # FFI return shapes41bun run skill/bun-win32/scripts/stub.ts {name} [--class=C] # paste-ready stubs4243# 4. Auditing (run after writing bindings)44bun run skill/bun-win32/scripts/audit.ts {name} # FFI↔TS↔header consistency (--all, --fix)45bun run skill/bun-win32/scripts/nullcheck.ts {name} # SAL nullability (--all, --fix, --strict)46bunx tsc --noEmit # type-check the package47```4849## Release5051```bash52rm bun.lock && bun install53bun run skill/bun-win32/scripts/preflight.ts54bun run skill/bun-win32/scripts/nullcheck.ts --all && bun run skill/bun-win32/scripts/audit.ts --all55cd packages/{name} && bun publish --access public --otp <code>56```5758## Scripts Reference5960| Script | What it does |61|---|---|62| `scripts/doctor.ts` | Prerequisites checker |63| `scripts/bootstrap.ts` | Orchestrated full pipeline |64| `scripts/catalog.ts` | dumpbin exports ∩ SDK headers → JSON |65| `scripts/scaffold.ts` | Template → package skeleton |66| `scripts/ffi-runtime.ts` | Probe FFI return-value shapes |67| `scripts/stub.ts` | catalog JSON → Symbols + method stubs |68| `scripts/audit.ts` | FFI↔TS↔header consistency auditor |69| `scripts/nullcheck.ts` | SAL-driven nullability auditor |70| `scripts/preflight.ts` | Lockfile staleness gate |7172## FFI Type Quick Reference7374| Win32 type | FFI | TS |75|---|---|---|76| `HANDLE`, `HWND`, `HKEY`, `HMODULE`… | `FFIType.u64` | `bigint` |77| `SIZE_T`, `*_PTR`, `LPARAM`, `LRESULT`, `WPARAM` | `FFIType.u64` | `bigint` |78| `LARGE_INTEGER`, `ULARGE_INTEGER` | `FFIType.i64` / `u64` | `bigint` |79| `DWORD`, `UINT`, `BOOL`, `HRESULT`, `INT`, `LONG`, `WORD`, `BYTE` | `FFIType.u32` / `i32` | `number` |80| `LPVOID`, `LPCWSTR`, `LPSTR`, `LPDWORD`, `LPBYTE`… | `FFIType.ptr` | `Pointer` |81| `void` | `FFIType.void` | `void` |8283**Decision rule:** Does the caller pass `.ptr` from a `Buffer`/`TypedArray` they allocated? Yes → `ptr`. No → `u64`.8485**NULL:** `u64 → 0n`, `ptr → null`, `u32 → 0`.8687## Key Files8889- `references/agents.md` — full AGENTS.md (binding rules, toolchain, FFI rules, prohibitions)90- `references/ai-core.md` — `@bun-win32/core` contract (Win32 base class, `.ptr` extension, types)91- `references/ai-all.md` — `@bun-win32/all` contract (re-export aggregator, when to use)92- `PROMPT.md` at WORKING_DIR — deep playbook for FFI mapping, nullability, audits9394## Prohibited9596- Bind exports not confirmed by `dumpbin //EXPORTS`97- Guess types/nullability — always verify vs SDK header + MS Learn98- Use `as any` / forced casts — fix the FFI mapping instead99- Reformat untouched files100- Ship without running `audit.ts --all` and `nullcheck.ts --all` (zero findings required)
involvex