Initial commit

Author: jdalton

.claude/commands/bake-fresh.md

@@ -0,0 +1,9 @@
+Clean the kitchen, bake from scratch, taste test.
+
+```bash
+pnpm --filter node-smol-builder clean
+pnpm --filter node-smol-builder build
+pnpm --filter node-smol-builder test
+```
+
+Report: build time, binary size, test results, any failures.

.claude/commands/quality-loop.md

@@ -0,0 +1,12 @@
+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 them all
+3. Run quality-scan again
+4. Repeat until zero issues or 5 iterations
+5. Commit fixes:
+   - If repo has only 1 commit: amend that commit
+   - Otherwise: new commit "fix: resolve quality scan issues (iteration N)"
+6. Run tests after fixes to verify nothing broke

.claude/commands/regen-patches.md

@@ -0,0 +1,9 @@
+Regenerate patches from pristine upstream source using the `regenerating-patches` skill.
+
+## Usage
+
+- `/regen-patches` - Regenerate all patches (Node.js + iocraft)
+- `/regen-patches node` - Node.js patches only
+- `/regen-patches iocraft` - iocraft patches only
+
+Use the Skill tool to invoke `regenerating-patches`, passing the argument to scope which patches to regenerate.

.claude/commands/squash-history.md

@@ -0,0 +1,3 @@
+Squash all commits on main branch to single "Initial commit" using the squashing-history skill.
+
+Creates backup branch, soft resets, verifies code integrity, gets confirmation, force pushes.

.claude/commands/update-cacache.md

@@ -0,0 +1,68 @@
+# update-cacache — Update the C/C++ cacache implementation
+
+Update `socket_cacache.h` to match the `@socketsecurity/lib` cacache spec.
+Run when the cacache format changes or cross-platform behavior needs updating.
+
+## What This Updates
+
+| File | Location |
+|------|----------|
+| `socket_cacache.h` | `packages/build-infra/src/socketsecurity/build-infra/socket_cacache.h` |
+
+## Process
+
+1. **Read the reference spec** from `@socketsecurity/lib`:
+   - Path resolution: `../socket-sdk-js/node_modules/@socketsecurity/lib/dist/paths/socket.js`
+   - Cacache wrapper: `../socket-sdk-js/node_modules/@socketsecurity/lib/dist/cacache.js`
+   - Also check ultrathink implementations for consistency:
+     - Rust: `../ultrathink/packages/acorn/lang/rust/src/socket_cacache.rs`
+     - Go: `../ultrathink/packages/acorn/lang/go/pkg/acorn/socket_cacache.go`
+
+2. **Update `socket_cacache.h`** to match:
+   - Path resolution: env var priority (SOCKET_CACACHE_DIR > SOCKET_HOME > HOME/USERPROFILE > tmpdir)
+   - Index: `index-v5/{sha256(key)[0:2]}/{sha256(key)[2:4]}/{sha256(key)[4:]}`
+   - Lines: `{sha1(json)}\t{json}\n`
+   - Content: `content-v2/sha512/{sha512_hex[0:2]}/{sha512_hex[2:4]}/{sha512_hex[4:]}`
+   - Integrity: `sha512-{base64_with_padding(sha512(data))}`
+   - Deletion: append `"integrity":null` (soft delete, not file delete)
+   - Metadata: always present as `{}` (never null, never omitted)
+
+3. **Cross-platform validation**:
+   - macOS: HOME → getenv("HOME"), crypto via CommonCrypto
+   - Linux: HOME → getenv("HOME"), crypto via OpenSSL
+   - Windows: USERPROFILE → getenv("USERPROFILE"), crypto via CryptoAPI
+   - Fallback: TEMP/TMP (Windows) or /tmp (Unix)
+
+4. **Compile test**:
+   ```bash
+   # macOS
+   cc -Wall -Wextra -I. test.c -o test -framework Security
+
+   # Linux
+   cc -Wall -Wextra -I. test.c -o test -lssl -lcrypto
+   ```
+
+5. **Cross-language verification**:
+   ```bash
+   # C writes, Node.js reads
+   ./test_write
+   node -e "require('cacache').get('~/.socket/_cacache', 'key').then(r => console.log(r.data))"
+   ```
+
+6. **Run Codex sanity check** — ask Codex to validate against spec.
+
+7. **Commit** with: `fix(build-infra): update socket_cacache.h to match @socketsecurity/lib vX.Y.Z`
+
+## Key Constraints
+
+- Header-only C (static functions) — no .c file needed
+- `extern "C"` wrappers for C++ inclusion
+- No external deps beyond platform crypto
+- Self-contained file I/O helpers (no file_utils.h dependency)
+- Internal functions prefixed `scache_` to avoid namespace collisions
+- Must produce entries readable by Node.js `cacache@20`
+
+## Reference Docs
+
+- Shared cache guide: `../ultrathink/packages/build-infra/docs/shared-cache.md`
+- Platform dirs: `../ultrathink/packages/build-infra/lib/platform-dirs.mjs`

.claude/commands/update.md

@@ -0,0 +1,30 @@
+# update - Update dependencies
+
+Invoke the `updating-$ARGUMENTS` skill to update a dependency.
+
+Usage: `/update <name>` (e.g., `/update node` invokes `updating-node`)
+
+## Available Names
+
+- `all` - Update everything (npm + all upstreams)
+- `node` - Node.js submodule + patch regeneration
+- `curl` - curl and mbedtls submodules
+- `lief` - LIEF binary manipulation library
+- `stubs` - Self-extracting stub binaries
+- `binsuite` - Orchestrate LIEF + stubs updates
+- `cjson` - cJSON library
+- `libdeflate` - libdeflate compression library
+- `lzfse` - LZFSE Apple compression library
+- `onnxruntime` - ONNX Runtime ML engine
+- `ink` - ink TUI framework
+- `iocraft` - iocraft TUI library
+- `yoga` - Yoga layout library
+- `fast-webstreams` - Vendor fast-webstreams from npm
+- `checksums` - Sync SHA-256 checksums from releases
+
+## Routing
+
+- `/update all` invokes the `updating` skill (no suffix)
+- All others invoke `updating-<name>`
+- Empty argument: list names and ask
+- Unknown name: suggest closest match

.claude/rules/gitmodules-version-comments.md

@@ -0,0 +1,50 @@
+# .gitmodules Version Comment Format
+
+**MANDATORY**: All submodule version comments in `.gitmodules` MUST follow this exact format.
+
+## Format Rules
+
+1. **Position**: Version comment appears on the line IMMEDIATELY BEFORE the `[submodule "path"]` line
+2. **Format**: `# package-X.Y.Z` where:
+   - `package` is the package name (lowercase)
+   - `X.Y.Z` is the semantic version using DOTS (never underscores)
+   - NO `v` prefix (use `1.0.0`, NOT `v1.0.0`)
+3. **Consistency**: ALL submodules use the same format - no exceptions
+
+## Example
+
+```gitmodules
+# curl-8.18.0
+[submodule "packages/curl-builder/upstream/curl"]
+	path = packages/curl-builder/upstream/curl
+	url = https://github.com/curl/curl.git
+# mbedtls-3.6.5
+[submodule "packages/curl-builder/upstream/mbedtls"]
+	path = packages/curl-builder/upstream/mbedtls
+	url = https://github.com/Mbed-TLS/mbedtls.git
+# lief-0.17.0
+[submodule "packages/lief-builder/upstream/lief"]
+	path = packages/lief-builder/upstream/lief
+	url = https://github.com/lief-project/LIEF.git
+```
+
+## Why This Matters
+
+- **Build scripts** use `getSubmoduleVersion()` which expects `# package-X.Y.Z\n[submodule ...]`
+- **CI workflows** use `grep -B 1` to extract versions from the line before the submodule
+- **Consistency** prevents bugs and makes version extraction reliable
+
+## Forbidden Patterns
+
+❌ `# v0.17.0` - NO v prefix
+❌ `# curl-8_18_0` - NO underscores (use dots)
+❌ Comment after URL line - MUST be before `[submodule ...]`
+❌ Different formats for different submodules - ALL must match
+
+## Validation
+
+When adding or updating submodules:
+1. Add version comment BEFORE `[submodule ...]` line
+2. Use format: `# package-VERSION` with dots
+3. Run `grep -B 1 'submodule-path' .gitmodules` to verify it can be extracted
+4. Check that build scripts can parse it with `getSubmoduleVersion()`

.claude/skills/quality-scan/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: quality-scan
+description: Scans the codebase for bugs, logic errors, caching issues, and workflow problems using specialized agents. Use when preparing for release, investigating quality issues, or running pre-merge checks.
+user-invocable: true
+allowed-tools: Task, Bash, Read, Grep, Glob, AskUserQuestion
+---
+
+# quality-scan
+
+Perform comprehensive quality analysis across the codebase using specialized agents. Clean up junk files first, then scan and generate a prioritized report with actionable fixes.
+
+## Scan Types
+
+1. **critical** - Crashes, security vulnerabilities, resource leaks, data corruption
+2. **logic** - Algorithm errors, edge cases, type guards, off-by-one errors
+3. **cache** - Cache staleness, race conditions, invalidation bugs
+4. **workflow** - Build scripts, CI issues, cross-platform compatibility
+5. **workflow-optimization** - CI optimization (build-required conditions on cached builds)
+6. **security** - GitHub Actions workflow security (zizmor scanner)
+7. **documentation** - README accuracy, outdated docs, missing documentation
+8. **patch-format** - Patch file format validation
+
+Agent prompts for each scan type are in `reference.md`.
+
+## Process
+
+### Phase 1: Validate Environment
+
+```bash
+git status
+```
+
+Warn about uncommitted changes but continue (scanning is read-only).
+
+### Phase 2: Update Dependencies
+
+```bash
+pnpm run update
+```
+
+Only update the current repository. Continue even if update fails.
+
+### Phase 3: Install zizmor
+
+Install zizmor for GitHub Actions security scanning, respecting the `minimumReleaseAge` from `.pnpmrc` (default 10080 minutes = 7 days). Query GitHub releases, find the latest stable release older than the threshold, and install via pipx/uvx. Skip the security scan if no release meets the age requirement.
+
+### Phase 4: Repository Cleanup
+
+Find and remove junk files (with user confirmation via AskUserQuestion):
+- SCREAMING_TEXT.md files outside `.claude/` and `docs/`
+- Test files in wrong locations
+- Temp files (`.tmp`, `.DS_Store`, `*~`, `*.swp`, `*.bak`)
+- Log files in root/package directories
+
+### Phase 5: Structural Validation
+
+```bash
+node scripts/check-consistency.mjs
+```
+
+Report errors as Critical findings. Warnings are Low findings.
+
+### Phase 6: Determine Scan Scope
+
+Ask user which scans to run using AskUserQuestion (multiSelect). Default: all scans.
+
+### Phase 7: Execute Scans
+
+For each enabled scan type, spawn a Task agent with the corresponding prompt from `reference.md`. Run sequentially in priority order: critical, logic, cache, workflow, then others.
+
+Each agent reports findings as:
+- File: path:line
+- Issue, Severity, Pattern, Trigger, Fix, Impact
+
+### Phase 8: Aggregate and Report
+
+- Deduplicate findings across scan types
+- Sort by severity: Critical > High > Medium > Low
+- Generate markdown report with file:line references, suggested fixes, and coverage metrics
+- Offer to save to `reports/quality-scan-YYYY-MM-DD.md`
+
+### Phase 9: Summary
+
+Report final metrics: dependency updates, structural validation results, cleanup stats, scan counts, and total findings by severity.