Skip to content

Commit d3fe509

Browse files
jdaltonjdalton
committed
Initial commit
0 parents  commit d3fe509

767 files changed

Lines changed: 153110 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Clean, Rebuild, and Test
2+
3+
Execute a complete validation cycle for node-smol-builder:
4+
5+
1. Clean build artifacts and checkpoints
6+
2. Rebuild with latest changes
7+
3. Run test suite
8+
4. Report: build size, test results, and any failures
9+
10+
Use this after making changes to binpress, binject, or build-infra that affect node-smol-builder.
11+
12+
Usage: `/clean-rebuild-test`
13+
14+
## Success Criteria
15+
16+
- ✅ Build artifacts cleaned successfully
17+
- ✅ Build completes without errors
18+
- ✅ All tests pass (100% pass rate)
19+
- ✅ Binary size reported
20+
- ✅ Build time reported
21+
- ✅ `<promise>BUILD_TEST_COMPLETE</promise>` emitted
22+
23+
## Completion Signal
24+
25+
Upon successful completion, emit:
26+
27+
```xml
28+
<promise>BUILD_TEST_COMPLETE</promise>
29+
```
30+
31+
## Edge Cases
32+
33+
**Build fails:**
34+
35+
```bash
36+
# Check build output for errors
37+
pnpm --filter node-smol-builder run build
38+
39+
# Common issues:
40+
# - Missing dependencies: pnpm install
41+
# - Corrupted checkpoints: pnpm run clean && pnpm run build
42+
# - C++ compilation errors: Check compiler version and flags
43+
```
44+
45+
**Tests fail:**
46+
47+
```bash
48+
# Run tests with verbose output
49+
pnpm --filter node-smol-builder test
50+
51+
# Check specific test failures
52+
# Fix issues before proceeding
53+
```
54+
55+
**Clean fails:**
56+
57+
```bash
58+
# Manually remove build artifacts
59+
rm -rf packages/node-smol-builder/build
60+
61+
# Then retry
62+
pnpm --filter node-smol-builder run build
63+
```
64+
65+
## Context
66+
67+
**Related Files:**
68+
69+
- Build package: `packages/node-smol-builder/`
70+
- Build script: `packages/node-smol-builder/scripts/binary-released/`
71+
- Build checkpoints: `packages/node-smol-builder/build/dev/checkpoints/`
72+
- Test directory: `packages/node-smol-builder/test/`
73+
74+
**Related Packages:**
75+
76+
- `binpress` - Binary compression (may affect build)
77+
- `binject` - Binary injection (may affect build)
78+
- `build-infra` - Shared build infrastructure
79+
80+
**Related Commands:**
81+
82+
- `/fix-and-commit` - Quick lint and test cycle with commit
83+
- `/commit-task` - Commit with progress tracking

‎.claude/commands/node-patcher.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
Regenerate Node.js patches from pristine source using the regenerating-node-patches skill.
2+
3+
Usage:
4+
5+
- `/node-patcher` - Regenerate all 16 patches
6+
- `/node-patcher 005` - Regenerate only patch 005
7+
8+
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.
9+
10+
If no patch number is provided, regenerate all patches with full workflow:
11+
12+
1. Backup existing patches with timestamp
13+
2. Reset upstream node submodule to SHA in .gitmodules
14+
3. Clean build artifacts and working directory
15+
4. Regenerate all 16 patches from pristine Node.js v25.5.0 source
16+
5. Validate each patch with dry-run before persisting
17+
18+
The skill follows this workflow for each patch:
19+
20+
- Obtain pristine file from Node.js v25.5.0
21+
- Apply modifications based on existing patch
22+
- Generate new patch using `diff -u` (NOT git diff)
23+
- Validate with `patch --dry-run`
24+
- Persist to patches directory
25+
26+
Report back when complete with summary of patches regenerated.
27+
28+
## Parameter Validation
29+
30+
**Valid patch numbers:** 001-014, 016-017
31+
32+
If a patch number is provided, validate it matches the pattern `NNN` where N is a digit:
33+
34+
- 001: common_gypi_fixes.patch
35+
- 002: polyfills.patch
36+
- 003: realm-vfs-binding.patch
37+
- 004: node-gyp-vfs-binject.patch
38+
- 005: node-binding-vfs.patch
39+
- 006: node-sea-smol-config.patch
40+
- 007: node-sea-header.patch
41+
- 008: node-sea-bin-binject.patch
42+
- 009: fix_v8_typeindex_macos.patch
43+
- 010: vfs_bootstrap.patch
44+
- 011: vfs_require_resolve.patch
45+
- 012: debug-utils-smol-sea-category.patch
46+
- 013: node-sea-silent-exit.patch
47+
- 014: fast-webstreams.patch
48+
- 016: http-perf-wire.patch
49+
- 017: http-parser-pool.patch
50+
51+
**Invalid patch number:**
52+
53+
```
54+
Error: Invalid patch number "999"
55+
Valid patch numbers: 001-014, 016-017
56+
```
57+
58+
## Success Criteria
59+
60+
- ✅ Skill `regenerating-node-patches` invoked successfully
61+
- ✅ All requested patches regenerated from pristine source
62+
- ✅ Each patch validated with `patch --dry-run`
63+
- ✅ Patches persisted to `patches/source-patched/` directory
64+
- ✅ No code differences detected (patches apply cleanly)
65+
- ✅ Backup created (full mode only)
66+
- ✅ `<promise>PATCH_REGEN_COMPLETE</promise>` emitted
67+
68+
## Completion Signal
69+
70+
Upon successful completion, the `regenerating-node-patches` skill emits:
71+
72+
```xml
73+
<promise>PATCH_REGEN_COMPLETE</promise>
74+
```
75+
76+
This signal indicates:
77+
78+
- All patches regenerated from pristine source
79+
- Each patch validated with dry-run
80+
- Patches persisted to patches directory
81+
- Ready for build testing and commit
82+
83+
## Edge Cases
84+
85+
For comprehensive edge case handling, refer to the `regenerating-node-patches` skill documentation.
86+
87+
**Common issues:**
88+
89+
- **Patch fails to apply**: Context lines don't match pristine file (skill auto-retries with increased context)
90+
- **Build fails after regeneration**: Review build log, check source files in additions/
91+
- **Patch header malformed**: Skill uses `diff -u` (not git diff) to avoid this
92+
- **Submodule not at correct SHA**: Full mode resets to SHA in .gitmodules
93+
94+
## Context
95+
96+
**Related Files:**
97+
98+
- Patches directory: `packages/node-smol-builder/patches/source-patched/`
99+
- Patch list: `packages/node-smol-builder/patches/source-patched/` (001-014, 016-017)
100+
- Node.js submodule: `packages/node-smol-builder/upstream/node/`
101+
- Upstream version: Node.js v25.5.0
102+
103+
**Related Skills:**
104+
105+
- `regenerating-node-patches` - The skill invoked by this command
106+
107+
**Related Commands:**
108+
109+
- `/sync` - Update Node.js and regenerate patches
110+
- `/sync-status` - Check current Node.js version

‎.claude/commands/quality-loop.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Run the quality-scan skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
2+
3+
## Process
4+
5+
1. Run quality-scan skill
6+
2. If issues found: fix ALL of them
7+
3. Run quality-scan again
8+
4. Repeat until:
9+
- Zero issues found (success), OR
10+
- 5 iterations completed (stop)
11+
5. Commit all fixes:
12+
- If repo has only 1 commit: **amend** that commit
13+
- Otherwise: create new commit with message "fix: resolve quality scan issues (iteration N)"
14+
15+
## Rules
16+
17+
- Fix every issue, not just "easy" ones
18+
- Do not skip architectural fixes
19+
- Run tests after fixes to verify nothing broke
20+
- Track iteration count and report progress
21+
22+
## Outstanding Architectural Issue (Requires Design Review)
23+
24+
### Checkpoint Cache Invalidation (High Severity)
25+
26+
**Issue**: Source package changes don't invalidate checkpoints properly.
27+
28+
**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.
29+
30+
**Scenario**:
31+
32+
1. Developer modifies `packages/binject/src/socketsecurity/binject/file.c`
33+
2. Runs `pnpm --filter node-smol-builder clean && pnpm build`
34+
3. `prepareExternalSources()` syncs binject → additions/source-patched/src/socketsecurity/binject/
35+
4. Cache key computed from additions/ files matches old checkpoint
36+
5. Build restores stale checkpoint, skips recompilation
37+
6. **Result**: Binary contains old binject code
38+
39+
**Impact**: Silent build incorrectness when modifying source packages
40+
41+
**Proposed Solutions** (require architectural review):
42+
43+
- Option 1: Include source package mtimes in cache key metadata
44+
- Option 2: Make `prepareExternalSources()` idempotent, always re-sync
45+
46+
**Files Affected**:
47+
48+
- packages/node-smol-builder/scripts/common/shared/build.mjs (collectBuildSourceFiles)
49+
- packages/node-smol-builder/scripts/common/shared/checkpoints.mjs (cache key generation)
50+
51+
**Status**: Documented for architectural review and future implementation

‎.claude/commands/sync-status.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# sync-status - Check Node.js version status
2+
3+
Check current Node.js version vs latest available upstream.
4+
5+
Quick read-only command to see if an update is available.
6+
7+
## Usage
8+
9+
```bash
10+
/sync-status
11+
```
12+
13+
## What It Shows
14+
15+
- Current version (from `.node-version`)
16+
- Current upstream tag (from submodule)
17+
- Latest available tag (from upstream)
18+
- Update available status
19+
20+
## Implementation
21+
22+
```bash
23+
# Current version
24+
CURRENT_VERSION=$(cat .node-version)
25+
echo "Current .node-version: $CURRENT_VERSION"
26+
27+
# Current upstream tag
28+
cd packages/node-smol-builder/upstream/node
29+
CURRENT_TAG=$(git describe --tags 2>/dev/null || echo "unknown")
30+
echo "Current upstream tag: $CURRENT_TAG"
31+
32+
# Fetch latest tags
33+
git fetch origin --tags --quiet 2>/dev/null
34+
35+
# Latest tag (exclude rc/beta)
36+
LATEST_TAG=$(git tag -l 'v*.*.*' --sort=-version:refname | grep -v 'rc' | grep -v 'beta' | head -1)
37+
LATEST_VERSION="${LATEST_TAG#v}" # Remove 'v' prefix
38+
39+
echo "Latest available: $LATEST_TAG ($LATEST_VERSION)"
40+
cd ../../..
41+
42+
# Compare
43+
if [ "$CURRENT_VERSION" = "$LATEST_VERSION" ]; then
44+
echo "✓ Up to date"
45+
else
46+
echo "⚠ Update available: $CURRENT_VERSION → $LATEST_VERSION"
47+
echo ""
48+
echo "To update: /sync"
49+
fi
50+
```
51+
52+
## Example Output
53+
54+
**Up to date:**
55+
56+
```
57+
Current .node-version: 25.5.0
58+
Current upstream tag: v25.5.0
59+
Latest available: v25.5.0 (25.5.0)
60+
✓ Up to date
61+
```
62+
63+
**Update available:**
64+
65+
```
66+
Current .node-version: 25.5.0
67+
Current upstream tag: v25.5.0
68+
Latest available: v25.6.0 (25.6.0)
69+
⚠ Update available: 25.5.0 → 25.6.0
70+
71+
To update: /sync
72+
```
73+
74+
## Success Criteria
75+
76+
- ✅ Current version retrieved from `.node-version`
77+
- ✅ Current upstream tag retrieved from submodule
78+
- ✅ Latest available tag fetched from upstream
79+
- ✅ Comparison result displayed (up to date or update available)
80+
- ✅ Status check completes without errors
81+
- ✅ No modifications made (read-only operation)
82+
83+
**Note:** This command does not emit a completion promise as it's a read-only status check.
84+
85+
## Edge Cases
86+
87+
**Submodule not initialized:**
88+
89+
```bash
90+
# Initialize submodule first
91+
git submodule update --init --recursive packages/node-smol-builder/upstream/node
92+
93+
# Then retry
94+
/sync-status
95+
```
96+
97+
**Git fetch fails (network issues):**
98+
99+
```bash
100+
# Command shows current state even if fetch fails
101+
# Latest tag will be based on locally cached tags
102+
103+
# Manual fetch:
104+
cd packages/node-smol-builder/upstream/node
105+
git fetch origin --tags
106+
cd ../../..
107+
```
108+
109+
**.node-version file missing:**
110+
111+
```bash
112+
# Create file with current version
113+
echo "25.5.0" > .node-version
114+
115+
# Or use sync to initialize
116+
/sync
117+
```
118+
119+
**Submodule is dirty or detached:**
120+
121+
```bash
122+
# Command still works but may show inconsistent state
123+
# To fix:
124+
cd packages/node-smol-builder/upstream/node
125+
git status
126+
git checkout <tag> # Checkout proper tag
127+
cd ../../..
128+
```
129+
130+
## Related Commands
131+
132+
- `/sync` - Update to latest Node.js version

0 commit comments

Comments
 (0)