refactor(build): adopt canonical make-package-exports generator + browser field

Generate package.json exports + the browser builtin-stub field via the wheelhouse-canonical generator + an opt-in scripts/repo/package-exports.config.mts. Retire the bespoke generator. browser-fetch → fetch/browser (fetchResponse); docs/api-index.md → docs/api.md. Includes the cascaded scanner + token-guard fixture fixes. On top of the 6.1.0 bump.

Author: jdalton

.claude/hooks/fleet/_shared/cdn-allowlist.mts

@@ -0,0 +1,137 @@
+/**
+ * @file Single source of truth for "is this a fleet-approved CDN / package
+ *   registry host?" — shared by the cdn-allowlist-guard Claude hook
+ *   (PreToolUse, blocks a fetch/download to an off-allowlist host) and the
+ *   commit-time check, so the two never drift (code is law, DRY).
+ *
+ *   The allowlist holds ONLY public package-registry and public CDN hosts —
+ *   the canonical registries every ecosystem advertises (crates.io, pypi.org,
+ *   …) plus the browser CDNs a front-end's CSP already exposes. These are
+ *   public knowledge, so the list is not sensitive: it is an allowlist, not a
+ *   secret, and the enforcement (not the secrecy of the list) is the value.
+ *
+ *   🚨 NEVER add an internal host here. A naive `https://` grep of a Socket
+ *   service repo surfaces `*.svc.cluster.local` Kubernetes service names
+ *   (artifact-search, github-interposer, metadata, nats, pgbouncer,
+ *   pipeline-gateway, svix, typosquat, …). Those are infra topology — a
+ *   public-surface-hygiene violation if committed. Seed this list from the
+ *   typed ecosystem-registry CONSTANTS that name fetch targets, never from a
+ *   blanket URL grep, and keep it to public registries / public CDNs only.
+ */
+
+import { findInvocation } from './shell-command.mts'
+
+// Public package-registry + download hosts the fleet's tooling legitimately
+// fetches from (seeded from depscan's ecosystem registry constants). Public
+// knowledge; all are canonical registries. Sorted alphabetically.
+export const ALLOWED_CDN_HOSTS: readonly string[] = [
+  'bower.io',
+  'chromewebstore.google.com',
+  'clojars.org',
+  'conda-forge.org',
+  'cran.r-project.org',
+  'crates.io',
+  'deno.land',
+  'elpa.gnu.org',
+  'forge.puppet.com',
+  'formulae.brew.sh',
+  'github.com',
+  'hackage.haskell.org',
+  'hex.pm',
+  'hub.docker.com',
+  'huggingface.co',
+  'juliahub.com',
+  'metacpan.org',
+  'npmjs.org',
+  'nuget.org',
+  'open-vsx.org',
+  'package.elm-lang.org',
+  'packagist.org',
+  'pkgs.racket-lang.org',
+  'proxy.golang.org',
+  'pub.dev',
+  'pypi.org',
+  'repo1.maven.org',
+  'rubygems.org',
+  'swiftpackageindex.com',
+  'vcpkg.io',
+]
+
+// Public CDN hosts a fleet front-end's CSP exposes (wildcard subdomains).
+// Public-by-design (sent in browser response headers). `*.` matches any
+// subdomain depth of the suffix.
+export const ALLOWED_CDN_WILDCARDS: readonly string[] = [
+  '*.apicdn.sanity.io',
+  '*.api.sanity.io',
+  '*.cloudfront.net',
+  '*.githubusercontent.com',
+  '*.jsdelivr.net',
+  '*.unpkg.com',
+]
+
+// True when `hostname` exactly matches an allowed host, or matches an allowed
+// wildcard suffix (`*.example.com` matches `a.example.com` and
+// `a.b.example.com`, but not the bare `example.com`). Compares
+// case-insensitively. Pass a bare hostname, not a URL.
+export function isAllowedCdnHost(hostname: string): boolean {
+  const host = hostname.toLowerCase()
+  for (let i = 0, { length } = ALLOWED_CDN_HOSTS; i < length; i += 1) {
+    if (host === ALLOWED_CDN_HOSTS[i]) {
+      return true
+    }
+  }
+  for (let i = 0, { length } = ALLOWED_CDN_WILDCARDS; i < length; i += 1) {
+    const suffix = ALLOWED_CDN_WILDCARDS[i]!.slice(1)
+    if (host.endsWith(suffix) && host.length > suffix.length) {
+      return true
+    }
+  }
+  return false
+}
+
+// Extract the hostname from a URL string, or undefined when it doesn't parse.
+export function hostnameOf(url: string): string | undefined {
+  try {
+    return new URL(url).hostname
+  } catch {
+    return undefined
+  }
+}
+
+// Find the first http(s) URL in a Bash command whose host is NOT allowed,
+// returning { url, host }. Used by the guard. Only flags fetch/download tools
+// (curl / wget / fetch) so unrelated URL mentions don't trip it. AST-matched
+// binary detection (no regex on the command), then a URL scan of the string.
+export interface DisallowedCdnHit {
+  url: string
+  host: string
+}
+
+const FETCH_BINARIES: readonly string[] = ['curl', 'wget', 'fetch', 'http', 'https']
+
+const URL_RE = /https?:\/\/[^\s"'`)>\]]+/g
+
+export function findDisallowedCdn(command: string): DisallowedCdnHit | undefined {
+  let invokesFetch = false
+  for (let i = 0, { length } = FETCH_BINARIES; i < length; i += 1) {
+    if (findInvocation(command, { binary: FETCH_BINARIES[i]! })) {
+      invokesFetch = true
+      break
+    }
+  }
+  if (!invokesFetch) {
+    return undefined
+  }
+  const matches = command.match(URL_RE)
+  if (!matches) {
+    return undefined
+  }
+  for (let i = 0, { length } = matches; i < length; i += 1) {
+    const url = matches[i]!
+    const host = hostnameOf(url)
+    if (host && !isAllowedCdnHost(host)) {
+      return { url, host }
+    }
+  }
+  return undefined
+}

.claude/hooks/fleet/_shared/package-manager-auto-update.mts

@@ -265,6 +265,36 @@ export const AUTO_UPDATE_CHECKS: readonly AutoUpdateCheck[] = [
   },
 ]
 
+export interface MacosPkgAutoUpdateEnv {
+  // The env-var name a shell `export` sets.
+  name: string
+  // The value that disables auto-update (always '1' today).
+  value: string
+  // The AutoUpdateCheck ids this knob disables, for traceability back to the
+  // source-of-truth detectors above.
+  managerIds: readonly string[]
+}
+
+// The env knobs setup-security-tools persists into the managed shell-rc block on
+// macOS so a mid-task `brew` / `npm` / `pnpm` run can't auto-update a tool under
+// a build/scan. Single source of truth shared with the detectors above — the
+// shell-rc bridge imports this list instead of hardcoding a divergent copy, so
+// adding a future macOS knob here flows into the persisted block automatically.
+// HOMEBREW_NO_AUTO_UPDATE maps to the 'homebrew' check; NO_UPDATE_NOTIFIER is
+// honored by both 'npm' and 'pnpm'. Listed alphabetically by env name.
+export const MACOS_PKG_AUTO_UPDATE_ENV: readonly MacosPkgAutoUpdateEnv[] = [
+  {
+    name: 'HOMEBREW_NO_AUTO_UPDATE',
+    value: '1',
+    managerIds: ['homebrew'],
+  },
+  {
+    name: 'NO_UPDATE_NOTIFIER',
+    value: '1',
+    managerIds: ['npm', 'pnpm'],
+  },
+]
+
 // True when `name` (a platform string) applies to the current OS.
 export function platformApplies(platform: PkgManagerPlatform): boolean {
   return platform === 'all' || platform === os.platform()

.claude/hooks/fleet/_shared/token-patterns.mts

@@ -211,3 +211,73 @@ export const SENSITIVE_NAME_FRAGMENTS: readonly string[] = [
   'AUTH',
   'CREDENTIAL',
 ]
+
+export interface SecretValuePattern {
+  // The regex that matches the literal secret VALUE shape (not the env-var
+  // name) — `AKIA…`, `ghp_…`, `sktsec_…`, a JWT, a PEM header.
+  re: RegExp
+  // Human label naming the vendor / kind, used in the block message.
+  label: string
+}
+
+// Literal secret-VALUE shapes — if any matches in arbitrary text, a real
+// credential has been pasted somewhere it shouldn't be. Distinct from the
+// `*_TOKEN_PATTERNS` above (those match an env-var KEY name). This is the
+// single source of truth shared by the Bash-time `token-guard`, the edit-time
+// `secret-content-guard`, and the commit-time scanners — one catalog so a new
+// vendor shape is added once and every gate picks it up (code is law, DRY).
+export const SECRET_VALUE_PATTERNS: readonly SecretValuePattern[] = [
+  { re: /sktsec_[A-Za-z0-9]{20,}/, label: 'Socket API key (sktsec_)' },
+  { re: /\bvtwn_[A-Za-z0-9_-]{8,}/, label: 'Val Town token (vtwn_)' },
+  { re: /\blin_api_[A-Za-z0-9_-]{8,}/, label: 'Linear API token (lin_api_)' },
+  { re: /\bsk-ant-[A-Za-z0-9_-]{20,}/, label: 'Anthropic API key (sk-ant-)' },
+  { re: /\bsk-proj-[A-Za-z0-9_-]{20,}/, label: 'OpenAI project key (sk-proj-)' },
+  { re: /\bhf_[A-Za-z0-9]{30,}/, label: 'Hugging Face token (hf_)' },
+  { re: /\bnpm_[A-Za-z0-9]{36}/, label: 'npm access token (npm_)' },
+  { re: /\bdop_v1_[a-f0-9]{64}/, label: 'DigitalOcean PAT (dop_v1_)' },
+  { re: /\bsk-[A-Za-z0-9_-]{20,}/, label: 'OpenAI/Anthropic-style secret key (sk-)' },
+  { re: /\bsk_live_[A-Za-z0-9_-]{16,}/, label: 'Stripe live secret (sk_live_)' },
+  { re: /\bsk_test_[A-Za-z0-9_-]{16,}/, label: 'Stripe test secret (sk_test_)' },
+  { re: /\bpk_live_[A-Za-z0-9_-]{16,}/, label: 'Stripe live publishable (pk_live_)' },
+  { re: /\brk_live_[A-Za-z0-9_-]{16,}/, label: 'Stripe live restricted (rk_live_)' },
+  { re: /\bghp_[A-Za-z0-9]{30,}/, label: 'GitHub personal access token (ghp_)' },
+  { re: /\bgho_[A-Za-z0-9]{30,}/, label: 'GitHub OAuth token (gho_)' },
+  // ghs_ / ghu_ char classes include `.` and `_` to match both the classic
+  // opaque format AND the stateless JWT format (≥36 is the min for both).
+  { re: /\bghs_[A-Za-z0-9._]{36,}/, label: 'GitHub app server token (ghs_)' },
+  { re: /\bghu_[A-Za-z0-9._]{36,}/, label: 'GitHub user access token (ghu_)' },
+  { re: /\bghr_[A-Za-z0-9]{30,}/, label: 'GitHub refresh token (ghr_)' },
+  { re: /\bgithub_pat_[A-Za-z0-9_]{20,}/, label: 'GitHub fine-grained PAT' },
+  { re: /\bglpat-[A-Za-z0-9_-]{16,}/, label: 'GitLab PAT (glpat-)' },
+  { re: /\bAKIA[0-9A-Z]{16}/, label: 'AWS access key ID (AKIA)' },
+  { re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/, label: 'Slack token (xox_-)' },
+  { re: /\bAIza[0-9A-Za-z_-]{35}/, label: 'Google API key (AIza)' },
+  {
+    re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/,
+    label: 'JWT',
+  },
+  {
+    re: /-----BEGIN [A-Z ]*PRIVATE KEY( BLOCK)?-----/,
+    label: 'private key (PEM block)',
+  },
+]
+
+export interface SecretValueHit {
+  label: string
+  // The matched secret substring, for the block message. Callers MUST redact
+  // before logging if the surface could be public.
+  match: string
+}
+
+// Return the first secret-VALUE shape matched in `text`, or undefined. Used by
+// every secret gate (Bash / edit / commit) so they share one detection list.
+export function scanSecretValues(text: string): SecretValueHit | undefined {
+  for (let i = 0, { length } = SECRET_VALUE_PATTERNS; i < length; i += 1) {
+    const { label, re } = SECRET_VALUE_PATTERNS[i]!
+    const m = re.exec(text)
+    if (m) {
+      return { label, match: m[0] }
+    }
+  }
+  return undefined
+}

.claude/hooks/fleet/cascade-first-triage-reminder/README.md

@@ -0,0 +1,34 @@
+# cascade-first-triage-reminder
+
+**Type:** Stop hook (soft reminder — never blocks).
+
+## Trigger
+
+Fires when the last assistant turn shows all of:
+
+1. a "not found" / "missing" / "unregistered" error shape, AND
+2. mention of a fleet-canonical artifact kind (`socket/*` rule, oxlint plugin,
+   `.config/fleet/`, `scripts/fleet/`, `.claude/hooks/fleet/`, `_shared/`, a
+   `check-*.mts`), AND
+3. evidence the assistant patched the **member** repo's copy (edit verbs aimed
+   at a `socket-*` path, "fixed the cascaded/live copy", `git apply`),
+
+without acknowledging the cascade-first path (re-cascade / "check the
+wheelhouse" / "incomplete cascade").
+
+## Why
+
+Member repos hold byte-copies of wheelhouse-canonical content. A missing or
+unregistered canonical artifact in a member is almost always an **incomplete
+cascade** (the cascade skips a fleet dir whose template source is git-dirty),
+not a real bug. Debugging or hand-patching the member's copy wastes cycles on
+code you don't own there — the fix lives upstream in the wheelhouse template,
+and re-cascading propagates it.
+
+## Bypass
+
+None — it's a non-blocking reminder. Acknowledge the cascade-first path (or
+genuinely confirm the artifact is absent from the wheelhouse too) and it stays
+quiet.
+
+See CLAUDE.md "Never fork fleet-canonical files locally" (cascade-first triage).

.claude/hooks/fleet/cascade-first-triage-reminder/index.mts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Claude Code Stop hook — cascade-first-triage-reminder.
+//
+// Nudges when the assistant reacted to a "not found" / "missing" /
+// "unregistered" error for a fleet-CANONICAL artifact by debugging or
+// hand-patching the MEMBER repo's copy, instead of checking the wheelhouse
+// template first and re-cascading. Member repos hold byte-copies of
+// wheelhouse-canonical content (`.config/fleet/**`, `scripts/fleet/**`,
+// `.claude/hooks/fleet/**`, the `socket/*` oxlint plugin, `_shared/` libs).
+// When one of those goes missing in a member, it is almost always an
+// incomplete cascade — the cascade SKIPS a fleet dir whose template source
+// is git-dirty — not a real bug to fix in the member.
+//
+// What this catches: an assistant turn that BOTH
+//   (a) shows a not-found-shaped error naming a canonical artifact, AND
+//   (b) describes editing / patching a member-repo copy of fleet content,
+// WITHOUT acknowledging the cascade-first path (check wheelhouse, re-cascade).
+//
+// Heuristic; false positives expected. Soft reminder, never blocks.
+// Per CLAUDE.md "Never fork fleet-canonical files locally" (cascade-first
+// triage).
+
+import process from 'node:process'
+
+import {
+  readLastAssistantText,
+  readStdin,
+  stripCodeFences,
+} from '../_shared/transcript.mts'
+
+interface StopPayload {
+  readonly transcript_path?: string | undefined
+}
+
+// A "not found"-shaped error for a canonical artifact: a rule, hook, lib,
+// or check that the tooling reports as absent/unregistered.
+const NOT_FOUND_RE =
+  /\b(not found|no such (?:rule|file|module|hook)|cannot find|missing|unregistered|does not exist|isn't registered|is not registered)\b/i
+
+// Mentions of a fleet-canonical artifact KIND (the things that live in the
+// wheelhouse and cascade out). A bare "file not found" without one of these
+// is too generic to flag. `plugin ['"]?socket` catches the oxlint loader's
+// own `Rule '…' not found in plugin 'socket'` message shape.
+const CANONICAL_ARTIFACT_RE =
+  /(socket\/[a-z0-9-]+|oxlint[- ]plugin|plugin ['"]?socket|\.config\/fleet\/|scripts\/fleet\/|\.claude\/hooks\/fleet\/|_shared\/|fleet[- ]canonical|check-[a-z-]+\.mts)/i
+
+// Evidence the assistant DEBUGGED / PATCHED the member copy rather than
+// re-cascading: edit verbs aimed at a member-repo path or "the copy".
+const MEMBER_PATCH_RE =
+  /\b(edited|patched|hand-?patch|fixed (?:the )?(?:member|downstream|live|cascaded) (?:copy|file)|git apply|added .* to (?:socket-(?:lib|cli|bin|btm|registry|sdk-js|mcp|packageurl-js|addon)))\b/i
+
+// The cascade-first acknowledgement that satisfies the check.
+const CASCADE_ACK_RE =
+  /\b(re-?cascade|cascade-first|check(?:ed)? the wheelhouse|wheelhouse (?:has|template)|sync-scaffolding|incomplete cascade|cascade issue|cascade incompleteness)\b/i
+
+async function main(): Promise<void> {
+  const payloadRaw = await readStdin()
+  let payload: StopPayload
+  try {
+    payload = JSON.parse(payloadRaw) as StopPayload
+  } catch {
+    process.exit(0)
+  }
+  const rawText = readLastAssistantText(payload.transcript_path)
+  if (!rawText) {
+    process.exit(0)
+  }
+  const text = stripCodeFences(rawText)
+
+  if (!NOT_FOUND_RE.test(text)) {
+    process.exit(0)
+  }
+  if (!CANONICAL_ARTIFACT_RE.test(text)) {
+    process.exit(0)
+  }
+  if (!MEMBER_PATCH_RE.test(text)) {
+    process.exit(0)
+  }
+  if (CASCADE_ACK_RE.test(text)) {
+    process.exit(0)
+  }
+
+  const lines = [
+    '[cascade-first-triage-reminder] A canonical artifact looked "not found" in a member repo and you patched the member copy.',
+    '',
+    '  Member repos hold byte-copies of wheelhouse-canonical content',
+    '  (.config/fleet/**, scripts/fleet/**, .claude/hooks/fleet/**, the',
+    '  socket/* oxlint plugin, _shared/ libs). A missing/unregistered one is',
+    '  almost always an INCOMPLETE CASCADE, not a bug to fix in the member.',
+    '',
+    '  Cascade-first triage:',
+    '    1. Check the wheelhouse template/ for the artifact.',
+    '    2. If present → re-cascade the member:',
+    '         node scripts/repo/sync-scaffolding/cli.mts --target <repo> --fix',
+    '    3. If the cascade SKIPS a fleet dir, its template source is git-dirty',
+    '       (WIP / a parallel session) — commit/reconcile the template, re-cascade.',
+    '    4. Only if genuinely absent from the wheelhouse is it a real authoring task.',
+    '',
+    '  Per CLAUDE.md "Never fork fleet-canonical files locally".',
+    '',
+  ]
+  process.stderr.write(lines.join('\n') + '\n')
+  process.exit(0)
+}
+
+main().catch(() => {
+  process.exit(0)
+})