Initial commit

Author: jdalton

.claude/commands/clean-rebuild-test.md

@@ -0,0 +1,83 @@
+# Clean, Rebuild, and Test
+
+Execute a complete validation cycle for node-smol-builder:
+
+1. Clean build artifacts and checkpoints
+2. Rebuild with latest changes
+3. Run test suite
+4. Report: build size, test results, and any failures
+
+Use this after making changes to binpress, binject, or build-infra that affect node-smol-builder.
+
+Usage: `/clean-rebuild-test`
+
+## Success Criteria
+
+- ✅ Build artifacts cleaned successfully
+- ✅ Build completes without errors
+- ✅ All tests pass (100% pass rate)
+- ✅ Binary size reported
+- ✅ Build time reported
+- ✅ `<promise>BUILD_TEST_COMPLETE</promise>` emitted
+
+## Completion Signal
+
+Upon successful completion, emit:
+
+```xml
+<promise>BUILD_TEST_COMPLETE</promise>
+```
+
+## Edge Cases
+
+**Build fails:**
+
+```bash
+# Check build output for errors
+pnpm --filter node-smol-builder run build
+
+# Common issues:
+# - Missing dependencies: pnpm install
+# - Corrupted checkpoints: pnpm run clean && pnpm run build
+# - C++ compilation errors: Check compiler version and flags
+```
+
+**Tests fail:**
+
+```bash
+# Run tests with verbose output
+pnpm --filter node-smol-builder test
+
+# Check specific test failures
+# Fix issues before proceeding
+```
+
+**Clean fails:**
+
+```bash
+# Manually remove build artifacts
+rm -rf packages/node-smol-builder/build
+
+# Then retry
+pnpm --filter node-smol-builder run build
+```
+
+## Context
+
+**Related Files:**
+
+- Build package: `packages/node-smol-builder/`
+- Build script: `packages/node-smol-builder/scripts/binary-released/`
+- Build checkpoints: `packages/node-smol-builder/build/dev/checkpoints/`
+- Test directory: `packages/node-smol-builder/test/`
+
+**Related Packages:**
+
+- `binpress` - Binary compression (may affect build)
+- `binject` - Binary injection (may affect build)
+- `build-infra` - Shared build infrastructure
+
+**Related Commands:**
+
+- `/fix-and-commit` - Quick lint and test cycle with commit
+- `/commit-task` - Commit with progress tracking

.claude/commands/node-patcher.md

@@ -0,0 +1,113 @@
+Regenerate Node.js patches from pristine source using the regenerating-node-patches skill.
+
+Usage:
+
+- `/node-patcher` - Regenerate all 16 patches
+- `/node-patcher 005` - Regenerate only patch 005
+
+If a patch number is provided (e.g., "005"), use the Skill tool to invoke the `regenerating-node-patches` skill with instructions to ONLY regenerate that specific patch. Skip the backup and cleanup steps for single-patch mode.
+
+If no patch number is provided, regenerate all patches with full workflow:
+
+1. Backup existing patches with timestamp
+2. Reset upstream node submodule to SHA in .gitmodules
+3. Clean build artifacts and working directory
+4. Regenerate all 16 patches from pristine Node.js v25.5.0 source
+5. Validate each patch with dry-run before persisting
+
+The skill follows this workflow for each patch:
+
+- Obtain pristine file from Node.js v25.5.0
+- Apply modifications based on existing patch
+- Generate new patch using `diff -u` (NOT git diff)
+- Validate with `patch --dry-run`
+- Persist to patches directory
+
+Report back when complete with summary of patches regenerated.
+
+## Parameter Validation
+
+**Valid patch numbers:** 001-014, 016-020
+
+If a patch number is provided, validate it matches the pattern `NNN` where N is a digit:
+
+- 001: common-gypi-lto.patch
+- 002: polyfills.patch
+- 003: realm-smol-bindings.patch
+- 004: node-gyp-smol-sources.patch
+- 005: smol-binding-macros.patch
+- 006: sea-smol-config.patch
+- 007: sea-smol-structs.patch
+- 008: sea-binject.patch
+- 009: v8-typeindex-macos.patch
+- 010: vfs-bootstrap.patch
+- 011: vfs-require-resolve.patch
+- 012: debug-smol-sea.patch
+- 013: sea-silent-exit.patch
+- 014: fast-webstreams.patch
+- 016: http-server-wire.patch
+- 017: http-parser-pool.patch
+- 018: smol-builtin-bindings.patch
+- 019: configure-postgres-iouring.patch
+- 020: smol-external-refs.patch
+
+**Invalid patch number:**
+
+```
+Error: Invalid patch number "999"
+Valid patch numbers: 001-014, 016-017
+```
+
+## Success Criteria
+
+- ✅ Skill `regenerating-node-patches` invoked successfully
+- ✅ All requested patches regenerated from pristine source
+- ✅ Each patch validated with `patch --dry-run`
+- ✅ Patches persisted to `patches/source-patched/` directory
+- ✅ No code differences detected (patches apply cleanly)
+- ✅ Backup created (full mode only)
+- ✅ `<promise>PATCH_REGEN_COMPLETE</promise>` emitted
+
+## Completion Signal
+
+Upon successful completion, the `regenerating-node-patches` skill emits:
+
+```xml
+<promise>PATCH_REGEN_COMPLETE</promise>
+```
+
+This signal indicates:
+
+- All patches regenerated from pristine source
+- Each patch validated with dry-run
+- Patches persisted to patches directory
+- Ready for build testing and commit
+
+## Edge Cases
+
+For comprehensive edge case handling, refer to the `regenerating-node-patches` skill documentation.
+
+**Common issues:**
+
+- **Patch fails to apply**: Context lines don't match pristine file (skill auto-retries with increased context)
+- **Build fails after regeneration**: Review build log, check source files in additions/
+- **Patch header malformed**: Skill uses `diff -u` (not git diff) to avoid this
+- **Submodule not at correct SHA**: Full mode resets to SHA in .gitmodules
+
+## Context
+
+**Related Files:**
+
+- Patches directory: `packages/node-smol-builder/patches/source-patched/`
+- Patch list: `packages/node-smol-builder/patches/source-patched/` (001-014, 016-017)
+- Node.js submodule: `packages/node-smol-builder/upstream/node/`
+- Upstream version: Node.js v25.5.0
+
+**Related Skills:**
+
+- `regenerating-node-patches` - The skill invoked by this command
+
+**Related Commands:**
+
+- `/sync` - Update Node.js and regenerate patches
+- `/sync-status` - Check current Node.js version

.claude/commands/quality-loop.md

@@ -0,0 +1,51 @@
+Run the quality-scan skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
+
+## Process
+
+1. Run quality-scan skill
+2. If issues found: fix ALL of them
+3. Run quality-scan again
+4. Repeat until:
+   - Zero issues found (success), OR
+   - 5 iterations completed (stop)
+5. Commit all fixes:
+   - If repo has only 1 commit: **amend** that commit
+   - Otherwise: create new commit with message "fix: resolve quality scan issues (iteration N)"
+
+## Rules
+
+- Fix every issue, not just "easy" ones
+- Do not skip architectural fixes
+- Run tests after fixes to verify nothing broke
+- Track iteration count and report progress
+
+## Outstanding Architectural Issue (Requires Design Review)
+
+### Checkpoint Cache Invalidation (High Severity)
+
+**Issue**: Source package changes don't invalidate checkpoints properly.
+
+**Root Cause**: Cache keys are computed AFTER `prepareExternalSources()` syncs source packages to additions/. Since cache keys hash files in additions/ (which are now synced), they match the checkpoint even though source packages changed.
+
+**Scenario**:
+
+1. Developer modifies `packages/binject/src/socketsecurity/binject/file.c`
+2. Runs `pnpm --filter node-smol-builder clean && pnpm build`
+3. `prepareExternalSources()` syncs binject → additions/source-patched/src/socketsecurity/binject/
+4. Cache key computed from additions/ files matches old checkpoint
+5. Build restores stale checkpoint, skips recompilation
+6. **Result**: Binary contains old binject code
+
+**Impact**: Silent build incorrectness when modifying source packages
+
+**Proposed Solutions** (require architectural review):
+
+- Option 1: Include source package mtimes in cache key metadata
+- Option 2: Make `prepareExternalSources()` idempotent, always re-sync
+
+**Files Affected**:
+
+- packages/node-smol-builder/scripts/common/shared/build.mjs (collectBuildSourceFiles)
+- packages/node-smol-builder/scripts/common/shared/checkpoints.mjs (cache key generation)
+
+**Status**: Documented for architectural review and future implementation

.claude/commands/squash-history.md

@@ -0,0 +1,30 @@
+Squash all commits on main branch to single "Initial commit" using the squashing-history skill.
+
+## What it does
+
+1. Creates timestamped backup branch
+2. Soft resets to first commit
+3. Creates single "Initial commit" with all code
+4. Verifies code integrity (zero differences)
+5. Gets user confirmation
+6. Force pushes to origin
+
+## Safety
+
+- Backup branch created before any destructive operations
+- Code verified byte-for-byte identical before force push
+- Explicit user confirmation required
+- Rollback possible via backup branch
+
+## Usage
+
+```bash
+/squash-history
+```
+
+## Rollback (if needed)
+
+```bash
+git reset --hard backup-YYYYMMDD-HHMMSS
+git push --force origin main
+```

.claude/commands/sync-checksums.md

@@ -0,0 +1,37 @@
+Sync SHA-256 checksums from GitHub releases to release-assets.json using the syncing-checksums skill.
+
+## What it does
+
+1. Fetches checksums.txt from latest GitHub releases
+2. Updates packages/build-infra/release-assets.json
+3. Validates JSON syntax
+4. Commits changes (if any)
+
+## Tools synced
+
+- lief - LIEF binary manipulation library
+- curl - curl with mbedTLS
+- stubs - Self-extracting stub binaries
+- libpq - PostgreSQL client library
+- binpress - Binary compression tool
+- binflate - Binary decompression tool
+- binject - Binary injection tool
+
+## Usage
+
+```bash
+/sync-checksums
+```
+
+## Manual commands
+
+```bash
+# Sync all tools
+pnpm --filter build-infra sync-checksums
+
+# Sync specific tool
+pnpm --filter build-infra sync-checksums --tool=lief
+
+# Dry run
+pnpm --filter build-infra sync-checksums --dry-run
+```