feat(release-kit): socket-release kit — payload, installer, bootstrap, gates, skills, tests

[John-David Dalton (jdalton)]

What

The SocketDev/sauce half of the Socket Release Kit: a copy-in publishing engine under release-kit/payload/scripts/socket-release/, its installer + manifest verifier, three consumer examples, four repo gates, a five-skill family, and a fully offline test matrix (192 tests across 20 files).

Design

The payload is the product. Everything a consumer runs lives in release-kit/payload/scripts/socket-release/ — 96 files, byte-pinned by a committed kit-manifest.json (sha256 of the POST-format bytes; gen-manifest.mts --check and the coherence gate refuse drift). The installer (release-kit/install.mts) copies channel-mapped subsets (npm, crates, github-release, brew, plus the implied common) into a consumer's scripts/socket-release/, plans by default, refuses per-file conflicts without --force, and --verify byte-compares forever after. Consumers exclude the tree from their own formatters/linters — same posture as this repo's own oxlint ignore tail — because a formatter rewrite would permanently break parity.

The bootstrap is an idempotent state machine. Eight steps in canonical order — preflight · placeholder · npm-access-permissive · github-env · staged-config · trusted-publisher · npm-access-staged-only · verify — each a read → pure classify → pure plan → apply → re-read module (passed only when the re-read says done, never false-green). Receipts are a reporting cache keyed to sha256(slug + package); live detection is the only authority. Exit codes pinned: 0 planned/passed · 1 failed · 2 usage · 3 blocked on a human gate · 4 precondition. --json emits exactly one schema-valid document (hand-rolled validateRunJson, no schema dependency); plan mode writes nothing, not even the state file, and renders auth-dead reads as planned/auth-unavailable instead of failing a machine it cannot fix. Only fail-closed reads (an unreachable registry is never "unpublished") fail in both modes.

The irreversible act is hard opt-in. Publishing <name>@0.0.0 burns the version forever, so a default --apply run STOPS at the reserve-name gate; only --apply --reserve <exact-package-name> publishes (mismatch = exit 2 with saw/wanted; --yes never substitutes). Detection short-circuits on a live name, so a double-publish is structurally unreachable.

Publishing access is permissive-then-staged-only (owner directive). The placeholder apply ensures BOTH direct and staged publishing right after the publish creates the package — the one window the wide shape is ever applied; npm-access-permissive is a no-op the moment the name is live (a re-run can never re-widen). After trusted publishing stands (a DAG precondition, so direct is never disabled before OIDC works), npm-access-staged-only unchecks direct publishing in the npm web UI through the ONE sanctioned browser session, and verify FAILS a package left permissive with the exact remediation command. The page parser refuses unknown shapes rather than classifying them, and the three access states ship as golden HTML fixtures.

Human moments are fleet gates. Eight factories in the kit's _shared/human-gate.mts (four ported + reserve-name, placeholder-promote, web-auth-approve, gh-env), mirror-tested for the 6-line shape in CANONICAL_GATES. Org secrets are never a gate: a negative test asserts no output ever names the release App credentials as human work. API before browser everywhere — gh api PUT + list-before-POST for environments, browser fallback as gate text only.

Brew is checksums-authority. brew-publish.mts bumps a binary-download formula only for an already-cut release (tag on origin, published non-draft, all templated assets present) and derives every sha256 from the release's own checksums.txt (both grammars) — never re-hashing. The tap commit is a GitHub-signed API commit direct to the tap default branch (never a PR), re-read and re-parsed before success is claimed.

Gates in this repo: release-kit-is-coherent (manifest freshness, marker leaks, pure-module import discipline), release-kit-launches-are-sanctioned (payload text scan + lawViolations(lawfulLaunchOptions()) === []), release-kit-workflows-are-env-mapped (no ${{ in run bodies, SHA-pinned dated uses:, permissions + concurrency), release-kit-types-resolve (payload tsc, release tier) — all auto-discovered by pnpm run check.

Adoption path

1. In the consumer: node <sauce>/release-kit/install.mts --target . --channels npm,github-release --apply, then pnpm add -D @socketsecurity/lib@6.5.2 @socketsecurity/sdk@4.1.3 playwright-core@1.61.1, commit.
2. node scripts/socket-release/bootstrap.mts (plan) → --apply, following nextCommand and the gates: reserve the name, approve npm's web-2FA, promote the staged placeholder, until verify reports stood-up (trusted publisher conforming, environments branch-restricted, workflows on origin, publishing access staged-only).
3. Releases from then on: bump + chore: bump version to <v>, dispatch npm publish from the Actions UI, promote with node scripts/socket-release/npm-publish.mts --approve; the tag + immutable release follow registry liveness (ORDER RULE). The four agent skills (npm-publish, gh-release, crates-publish, brew-tap) teach an agent each flow end to end; socket-release is the user-invoked installer skill.

The consumer-side install (deliverable 2) rides this payload byte-identically and is tracked separately.

Verification

• pnpm exec vitest run test/repo/{unit,integration}/release-kit: 20 files, 192 tests, all passing, fully offline (fake seams; synthetic authority-annotated fixtures; no browser, no socket).
• node release-kit/gen-manifest.mts --check exits 0 AFTER pnpm run format (R11 — a second format changes nothing).
• All four new repo checks exit 0; pnpm run lint --all and pnpm run type pass; the payload tsc program is clean.
• pnpm run generate:check passes with the five marketplace entries.
• Real smokes: installer --apply/--verify into a temp consumer (81 files, byte-identical), bootstrap.mts --help → 0, --apply --dry-run → 2, unknown step → 2, --status → 0, and a real --dry-run --json plan run → exit 0, one schema-valid document, zero writes.
• Nothing real happened: no publish, no dispatch, no environment created, no registry or GitHub mutation of any kind.

Pre-existing check --all failures on main (dispatch-table, ci.yml fleet env, stable-aliases, cargo-soak fixture, CLAUDE.md rule gaps, skill catalog, gen doc script path, telemetry env, hook overlap) are untouched by this branch.