yao-pkg
diff --git a/‎.claude/rules/development.md‎
Lines changed: 36 additions & 0 deletions b/‎.claude/rules/development.md‎
Lines changed: 36 additions & 0 deletions
diff --git a/‎.claude/rules/git-and-pr.md‎
Lines changed: 26 additions & 0 deletions b/‎.claude/rules/git-and-pr.md‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎.claude/rules/platform-and-vfs.md‎
Lines changed: 37 additions & 0 deletions b/‎.claude/rules/platform-and-vfs.md‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎.claude/rules/project.md‎
Lines changed: 24 additions & 0 deletions b/‎.claude/rules/project.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎.claude/rules/testing.md‎
Lines changed: 31 additions & 0 deletions b/‎.claude/rules/testing.md‎
Lines changed: 31 additions & 0 deletions
@@ -0,0 +1,36 @@
+---
+description: Build, lint, formatting, and TypeScript rules
+---
+
+# Development
+
+## Build
+
+```bash
+npm run build    # Required before testing — compiles lib/ to lib-es5/
+npm run start    # Watch mode with auto-rebuild
+```
+
+## Lint & Format
+
+```bash
+npm run lint         # Check both ESLint + Prettier
+npm run fix          # Auto-fix all issues
+npm run lint:code    # ESLint only
+npm run lint:style   # Prettier only
+```
+
+- Always run `npm run lint` before committing. Fix all issues — never push dirty code.
+- Console statements are disallowed in production code but allowed in test files.
+
+## TypeScript
+
+- Strict mode enabled. Target: ES2022. Module system: CommonJS.
+- Edit `lib/*.ts` only — never edit `lib-es5/*.js` directly.
+- Requires Node.js >= 22.0.0.
+
+## Dependencies
+
+- Keep runtime dependencies minimal — they affect all packaged apps.
+- Use exact or caret ranges.
+- `pkg-fetch` provides pre-compiled Node.js binaries.
@@ -0,0 +1,26 @@
+---
+description: Git workflow, commit conventions, and PR rules
+---
+
+# Git & PR Workflow
+
+## CRITICAL: PR Target
+
+- ALWAYS create PRs against `yao-pkg/pkg` (this fork).
+- NEVER target `vercel/pkg` — it is archived and read-only.
+
+## Commits
+
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`, `docs:`
+- Default branch: `main`. Tag format: `v${version}`.
+- Branch protection requires passing CI checks.
+
+## Before Committing
+
+1. Clean test artifacts from test directories (`*.exe`, `*-linux`, `*-macos`, `*-win.exe`).
+2. Run `npm run lint` and fix all issues.
+3. Show `git status --short` and get user approval before committing.
+
+## Release
+
+Uses `release-it` with conventional commits (`npm run release`). This runs linting, generates changelog, creates a git tag, pushes to GitHub, and publishes to npm as `@yao-pkg/pkg`.
@@ -0,0 +1,37 @@
+---
+description: VFS, native addons, cross-compilation, ESM, and platform-specific notes
+paths:
+  - 'prelude/**'
+  - 'lib/**'
+---
+
+# Platform & Virtual Filesystem
+
+## VFS Path Handling
+
+- Packaged apps use `/snapshot/` prefix (or `C:\snapshot\` on Windows).
+- Use `__dirname`/`__filename` for snapshot files, `process.cwd()` for runtime fs.
+- Path handling differs between packaged and non-packaged execution.
+
+## Native Addons
+
+- Extracted to `$HOME/.cache/pkg/` at runtime. Must match target Node.js version.
+- `linuxstatic` target cannot load native bindings.
+- Add `.node` files to `assets` if not detected automatically.
+
+## Cross-Compilation
+
+- Bytecode generation requires the target architecture binary.
+- Use `--no-bytecode` for cross-arch builds.
+- Linux: QEMU for emulation. macOS: Rosetta 2 for arm64 building x64.
+
+## ESM
+
+- Requires `--options experimental-require-module` on Node.js < 22.12.0.
+- Check existing dictionary files for package-specific ESM handling.
+
+## Platform Notes
+
+- **Linux**: `linuxstatic` target for max portability.
+- **macOS**: arm64 requires code signing (`codesign` or `ldid`).
+- **Windows**: `.exe` extension required; native modules must match target arch.
@@ -0,0 +1,24 @@
+---
+description: Project overview, structure, and key files for yao-pkg/pkg
+---
+
+# Project Overview
+
+`pkg` packages Node.js projects into standalone executables for Linux, macOS, and Windows. It supports Node.js 22 and newer, virtual filesystem bundling, V8 bytecode compilation, native addons, and compression (Brotli, GZip).
+
+This is `yao-pkg/pkg` — a maintained fork of the archived `vercel/pkg`.
+
+## Repository Structure
+
+- `lib/` — TypeScript source (compiled to `lib-es5/` via `npm run build`)
+- `prelude/` — Bootstrap code injected into packaged executables
+- `dictionary/` — Package-specific configs for known npm packages
+- `test/` — Numbered test directories (`test-XX-name/`)
+- `.github/workflows/` — CI/CD (GitHub Actions)
+
+## Key Entry Points
+
+- `lib/index.js` — API entry point
+- `lib/bin.js` — CLI entry point
+- `prelude/bootstrap.js` — Injected into every packaged executable
+- `dictionary/*.js` — Special handling for specific npm packages
@@ -0,0 +1,31 @@
+---
+description: Test commands, organization, and patterns
+paths:
+  - 'test/**'
+---
+
+# Testing
+
+## Commands
+
+```bash
+npm run build                          # Always build first
+npm run test:22                        # Test with Node.js 22
+npm run test:host                      # Test with host Node.js version
+node test/test.js node22 no-npm test-50-*   # Run specific test pattern
+```
+
+## Organization
+
+- Tests live in `test/test-XX-descriptive-name/` directories (XX = execution order).
+- Each test has a `main.js` entry point using utilities from `test/utils.js`.
+- `test-79-npm/` — npm package integration tests (only-npm).
+- `test-42-fetch-all/` — verifies patches exist for all Node.js versions.
+
+## Writing Tests
+
+1. Create `test/test-XX-descriptive-name/` with a `main.js`
+2. Use `utils.pkg.sync()` to invoke pkg
+3. Verify outputs, clean up with `utils.filesAfter()`
+
+Test artifacts (`*.exe`, `*-linux`, `*-macos`, `*-win.exe`) must be cleaned from test directories before committing.