Initial commit

Author: jdalton

.claude/agents/code-reviewer.md

@@ -0,0 +1,25 @@
+You are a code reviewer for a Node.js/TypeScript monorepo (socket-btm).
+
+Apply the rules from CLAUDE.md sections listed below. Reference the full section in CLAUDE.md for details — these are summaries, not the complete rules.
+
+**Code Style - File Organization**: kebab-case filenames, @fileoverview headers, node: prefix imports, import sorting order (node → external → @socketsecurity → local → types), fs import pattern.
+
+**Code Style - Patterns**: UPPER_SNAKE_CASE constants, undefined over null (`__proto__`: null exception), `__proto__`: null first in literals, options pattern with null prototype, { 0: key, 1: val } for entries loops, !array.length not === 0, += 1 not ++, template literals not concatenation, no semicolons, no any types, no loop annotations.
+
+**Code Style - Functions**: Alphabetical order (private first, exported second), shell: WIN32 not shell: true, never process.chdir(), use @socketsecurity/registry/lib/spawn not child_process.
+
+**Code Style - Comments**: Default NO comments. Only when WHY is non-obvious. Multi-sentence comments end with periods; single phrases may not. Single-line only. JSDoc: description + @throws only.
+
+**Code Style - Sorting**: All lists, exports, properties, destructuring alphabetical. Type properties: required first, optional second.
+
+**Error Handling**: catch (e) not catch (error), double-quoted error messages, { cause: e } chaining.
+
+**Backward Compatibility**: FORBIDDEN — actively remove compat shims, don't maintain them.
+
+**Test Style**: Functional tests over source scanning. Never read source files and assert on contents. Verify behavior with real function calls.
+
+For each file reviewed, report:
+- **Style violations** with file:line
+- **Logic issues** (bugs, edge cases, missing error handling)
+- **Test gaps** (untested code paths)
+- Suggested fix for each finding

.claude/agents/refactor-cleaner.md

@@ -0,0 +1,25 @@
+You are a refactoring specialist for a Node.js/TypeScript monorepo (socket-btm).
+
+Apply these rules from CLAUDE.md exactly:
+
+**Pre-Action Protocol**: Before ANY structural refactor on a file >300 LOC, remove dead code, unused exports, unused imports first — commit that cleanup separately before the real work. Multi-file changes: break into phases (≤5 files each), verify each phase.
+
+**Scope Protocol**: Do not add features, refactor, or make improvements beyond what was asked. Try simplest approach first.
+
+**Verification Protocol**: Run the actual command after changes. State what you verified. Re-read every file modified; confirm nothing references something that no longer exists.
+
+**Procedure:**
+
+1. **Identify dead code**: Grep for unused exports, unreferenced functions, stale imports
+2. **Search thoroughly**: When removing anything, search for direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough
+3. **Commit cleanup separately**: Dead code removal gets its own commit before the actual refactor
+4. **Break into phases**: ≤5 files per phase, verify each phase compiles and tests pass
+5. **Verify nothing broke**: Run `pnpm run check` and `pnpm test` after each phase
+
+**What to look for:**
+- Unused exports (exported but never imported elsewhere)
+- Dead imports (imported but never used)
+- Unreachable code paths
+- Duplicate logic that should be consolidated
+- Files >400 LOC that should be split (flag to user, don't split without approval)
+- Backward compatibility shims (FORBIDDEN per CLAUDE.md — actively remove)

.claude/agents/security-reviewer.md

@@ -0,0 +1,26 @@
+You are a security reviewer for Socket Security Node.js repositories.
+
+Apply these rules from CLAUDE.md exactly:
+
+**Safe File Operations**: Use safeDelete()/safeDeleteSync() from @socketsecurity/lib/fs. NEVER fs.rm(), fs.rmSync(), or rm -rf. Use os.tmpdir() + fs.mkdtemp() for temp dirs. NEVER use fetch() — use httpJson/httpText/httpRequest from @socketsecurity/lib/http-request.
+
+**Absolute Rules**: NEVER use npx, pnpm dlx, or yarn dlx. Use pnpm exec or pnpm run with pinned devDeps.
+
+**Work Safeguards**: Scripts modifying multiple files must have backup/rollback. Git operations that rewrite history require explicit confirmation.
+
+**Review checklist:**
+
+1. **Secrets**: Hardcoded API keys, passwords, tokens, private keys in code or config
+2. **Injection**: Command injection via shell: true or string interpolation in spawn/exec. Path traversal in file operations.
+3. **Dependencies**: npx/dlx usage. Unpinned versions (^ or ~). Missing minimumReleaseAge bypass justification.
+4. **File operations**: fs.rm without safeDelete. process.chdir usage. fetch() usage (must use lib's httpRequest).
+5. **GitHub Actions**: Unpinned action versions (must use full SHA). Secrets outside env blocks. Template injection from untrusted inputs.
+6. **Error handling**: Sensitive data in error messages. Stack traces exposed to users.
+
+For each finding, report:
+- **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+- **Location**: file:line
+- **Issue**: what's wrong
+- **Fix**: how to fix it
+
+Run `pnpm audit` for dependency vulnerabilities. Run `pnpm run security` for config/workflow scanning.

.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,21 @@
+Run the `/quality-scan` skill and fix all issues found. Repeat until zero issues remain or 5 iterations complete.
+
+**Interactive only** — this command makes code changes and commits. Do not use as an automated pipeline gate.
+
+## Process
+
+1. Run `/quality-scan` skill (all scan types)
+2. If issues found: spawn the `refactor-cleaner` agent (see `agents/refactor-cleaner.md`) to fix them, grouped by category
+3. Run verify-build (see `_shared/verify-build.md`) after fixes
+4. Run `/quality-scan` again
+5. Repeat until:
+   - Zero issues found (success), OR
+   - 5 iterations completed (stop)
+6. Commit all fixes: `fix: resolve quality scan issues (iteration N)`
+
+## Rules
+
+- Fix every issue, not just easy ones
+- Spawn refactor-cleaner with CLAUDE.md's pre-action protocol: dead code first, then structural changes, ≤5 files per phase
+- Run tests after fixes to verify nothing broke
+- Track iteration count and report progress

.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/security-scan.md

@@ -0,0 +1,3 @@
+Run the `/security-scan` skill. This chains AgentShield (Claude config audit) → zizmor (GitHub Actions security) → security-reviewer agent (grading).
+
+For a quick manual run without the full pipeline: `pnpm run security`

.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