AGENTS.md

AGENTS

Overview

• Package name: unsafe-pointer
• Purpose: expose a tiny unsafe Node-API addon for turning ArrayBuffer memory into raw pointers and raw pointers back into ArrayBuffer aliases.
• Runtime loading uses node-gyp-build.
• Prebuild generation uses zig-build.
• Source-build fallback uses node-gyp.

Tooling

• Install tools with mise install.
• Tool versions are pinned in mise.toml.
• Use bun for local repo tasks.
• Use npm in packed-tarball verification flows and publish flows.

Important Files

• index.d.ts: The spec for this package. When the user updates this spec, the agent should update the native implementation to match
• src/binding.c: native implementation
• index.mjs: generated ESM wrapper
• index.js: CommonJS loader via node-gyp-build
• scripts/codegen-index-mjs.mts: generates index.mjs from index.d.ts
• scripts/zig-build-prebuilds.mts: builds and publishes prebuilds
• test/register-unsafe-pointer-tests.js: shared runtime tests
• dist-test/index.test.js: packed-tarball verification test
• .github/workflows/ci.yml: CI and publish workflow

Commands

• Install deps: bun install
• Format check: bun run fmt --check
• Typecheck: bun run typecheck
• Rebuild local addon from source: bun run rebuild
• Run tests: bun run test
• Generate JS wrapper: bun run build:js
• Build native prebuilds: bun run build:c
• Full build, all platforms: bun run build

Generated Files

• index.d.ts is the source of truth for the JS-facing API.
• index.mjs is generated from index.d.ts. Do not hand-edit it.
• bun run build:js must be stable. Running it should not introduce formatter drift.

Native/API Sync Rules

• If the public API changes, update all of:
  • src/binding.c
  • test/register-unsafe-pointer-tests.js
  • README.md
  • generated index.mjs, via bun run build:js
• Keep the native implementation simple and direct. Avoid duplicating logic, share with helper functions.
• The addon is plain C with Node-API. Keep it small and dependency-free.
• binding.gyp exists for source builds. Do not remove the node-gyp fallback.

Prebuilds

• Supported prebuild targets are:
  • darwin-x64
  • darwin-arm64
  • linux-x64-glibc
  • linux-arm64-glibc
  • linux-x64-musl
  • linux-arm64-musl
  • win32-x64
  • win32-arm64
• Linux filenames include the libc tag.
• Darwin and Windows filenames do not.
• Windows targets must be built in separate zig-build batches to avoid node.lib races.

CI

• CI has two main jobs:
  • build: format check, typecheck, build, tracked-file cleanliness check, tests, npm pack
  • dist-test: install the packed tarball and test both prebuilt and source-build paths across OS/arch variants
• Pushes to main may publish to npm via GitHub OIDC trusted publishing after dist-test passes.
• Musl verification runs inside node:22-alpine via docker run from the Linux runners.
• CI fails if bun run build changes tracked files.
• Before pushing, the safe local gate is:
  • bun run fmt --check
  • bun run typecheck
  • bun run build
  • git diff --exit-code
  • bun run test

PR Flow

• Use gh for PR work.
• Push implementation work to a branch, then open or update a PR with gh pr create and gh pr view.
• After each push, monitor checks with gh pr checks <pr> --watch.
• If CI fails, inspect the failing run with gh pr checks <pr> and gh run view <run-id> --job <job-id> --log-failed.
• Keep iterating until the PR is green.
• Once implementation is complete and the remaining work is just burning through CI or test failures, ask the user whether to enable auto-merge.
• Do not enable auto-merge without asking.
• If approved, prefer gh pr merge --auto --squash.

Docs And Style

• Keep docs dry and concise.
• Use sentence case. Sentences start with a capital letter and end with punctuation.
• Prefer TypeScript in README examples.
• Author the README API section from index.d.ts.
• Do not soften the safety language. This package can crash the process, corrupt memory, or enable attacker-controlled execution.
• Preserve existing naming and packaging conventions unless there is a concrete reason to change them.