Agent Skills › involvex/youtube-music-cli › bun-win32

bun-win32

GitHub

Bun Win32 FFI绑定开发全生命周期技能，涵盖从DLL生成包、脚手架搭建到FFI一致性审计及空值检查的自动化流程。

.claude/skills/bun-win32/SKILL.md involvex/youtube-music-cli

Trigger Scenarios

生成新的Win32 DLL绑定包审计FFI与TypeScript及头文件的一致性修复函数返回值的可空性标注执行完整的绑定流水线

Install

npx skills add involvex/youtube-music-cli --skill bun-win32 -g -y

More Options

Non-standard path

npx skills add https://github.com/involvex/youtube-music-cli/tree/main/.claude/skills/bun-win32 -g -y

Use without installing

npx skills use involvex/youtube-music-cli@bun-win32

指定 Agent (Claude Code)

npx skills add involvex/youtube-music-cli --skill bun-win32 -a claude-code -g -y

安装 repo 全部 skill

npx skills add involvex/youtube-music-cli --all -g -y

预览 repo 内 skill

npx skills add involvex/youtube-music-cli --list

SKILL.md

Frontmatter

{
    "name": "bun-win32",
    "engines": [
        "opencode"
    ],
    "description": "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.\n"
}

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)