fix(ci): clear the lint, test, and doc gates

CLAUDE.md

@@ -148,5 +148,6 @@ Advice and critical assessment ONLY — never for making code changes. Consult b
 - 🚨 A failure AFTER the tag step burns that version; move the hint to the next patch, never re-dispatch the same number. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)
 - 🚨 Never dispatch a real run (`dry-run=false`) and never approve a stage — both are human actions, and stage approval needs browser 2FA. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)
 - 🚨 The USER names the release version; prepare the bump commit only after they do. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)
-- Between releases `package.json` carries an `X.Y.Z-prerelease` hint and notes accrue under CHANGELOG's `## [Unreleased]`; the bump strips the hint and promotes that section. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)
+- Between releases `package.json` carries an `X.Y.Z-prerelease` hint; the bump strips it. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)
+- Notes accrue under CHANGELOG's `## [Unreleased]`; the bump promotes that section into the release. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)
 - 🚨 `v1.x` is the consumable line and owns the `latest` dist-tag; the default branch carries the 2.x PRERELEASE line and is refused `latest`. [`releasing-v1x`](docs/agents.md/repo/releasing-v1x.md)

docs/references/repo/cdxgen-flags.md

@@ -0,0 +1,85 @@
+# cdxgen 11.2.7 flag reference
+
+Verbatim `--help` output of the cdxgen version this repo maps flags for. The
+`yargsConfig` in
+[`packages/cli/src/commands/manifest/cmd-manifest-cdxgen.mts`](../../../packages/cli/src/commands/manifest/cmd-manifest-cdxgen.mts)
+is derived from it: cdxgen parses its own args with yargs, so the Socket CLI
+mirrors that config instead of re-declaring every flag in meow.
+
+This lives in a doc rather than inline because it is a snapshot of one exact
+version, and that is what makes it useful — a version that gets unpublished
+cannot be fetched again. To move to a newer cdxgen, run the command below and
+replace the block with its output.
+
+```console
+$ npx @cyclonedx/cdxgen@11.2.7 --help
+
+Options:
+  -o, --output                 Output file. Default bom.json                                       [default: "bom.json"]
+  -t, --type                   Project type. Please refer to https://cyclonedx.github.io/cdxgen/#/PROJECT_TYPES for supp
+                               orted languages/platforms.                                                        [array]
+      --exclude-type           Project types to exclude. Please refer to https://cyclonedx.github.io/cdxgen/#/PROJECT_TY
+                               PES for supported languages/platforms.
+  -r, --recurse                Recurse mode suitable for mono-repos. Defaults to true. Pass --no-recurse to disable.
+                                                                                               [boolean] [default: true]
+  -p, --print                  Print the SBOM as a table with tree.                                            [boolean]
+  -c, --resolve-class          Resolve class names for packages. jars only for now.                            [boolean]
+      --deep                   Perform deep searches for components. Useful while scanning C/C++ apps, live OS and oci i
+                               mages.                                                                          [boolean]
+      --server-url             Dependency track url. Eg: https://deptrack.cyclonedx.io
+      --skip-dt-tls-check      Skip TLS certificate check when calling Dependency-Track.      [boolean] [default: false]
+      --api-key                Dependency track api key
+      --project-group          Dependency track project group
+      --project-name           Dependency track project name. Default use the directory name
+      --project-version        Dependency track project version                                   [string] [default: ""]
+      --project-id             Dependency track project id. Either provide the id or the project name and version togeth
+                               er                                                                               [string]
+      --parent-project-id      Dependency track parent project id                                               [string]
+      --required-only          Include only the packages with required scope on the SBOM. Would set compositions.aggrega
+                               te to incomplete unless --no-auto-compositions is passed.                       [boolean]
+      --fail-on-error          Fail if any dependency extractor fails.                                         [boolean]
+      --no-babel               Do not use babel to perform usage analysis for JavaScript/TypeScript projects.  [boolean]
+      --generate-key-and-sign  Generate an RSA public/private key pair and then sign the generated SBOM using JSON Web S
+                               ignatures.                                                                      [boolean]
+      --server                 Run cdxgen as a server                                                          [boolean]
+      --server-host            Listen address                                                     [default: "127.0.0.1"]
+      --server-port            Listen port                                                             [default: "9090"]
+      --install-deps           Install dependencies automatically for some projects. Defaults to true but disabled for c
+                               ontainers and oci scans. Use --no-install-deps to disable this feature.
+                                                                                               [boolean] [default: true]
+      --validate               Validate the generated SBOM using json schema. Defaults to true. Pass --no-validate to di
+                               sable.                                                          [boolean] [default: true]
+      --evidence               Generate SBOM with evidence for supported languages.           [boolean] [default: false]
+      --spec-version           CycloneDX Specification version to use. Defaults to 1.6
+                                                                        [number] [choices: 1.4, 1.5, 1.6, 1.7] [default: 1.6]
+      --filter                 Filter components containing this word in purl or component.properties.value. Multiple va
+                               lues allowed.                                                                     [array]
+      --only                   Include components only containing this word in purl. Useful to generate BOM with first p
+                               arty components alone. Multiple values allowed.                                   [array]
+      --author                 The person(s) who created the BOM. Set this value if you're intending the modify the BOM
+                               and claim authorship.                               [array] [default: "OWASP Foundation"]
+      --profile                BOM profile to use for generation. Default generic.
+  [choices: "appsec", "research", "operational", "threat-modeling", "license-compliance", "generic", "machine-learning",
+                                                       "ml", "deep-learning", "ml-deep", "ml-tiny"] [default: "generic"]
+      --exclude                Additional glob pattern(s) to ignore                                              [array]
+      --export-proto           Serialize and export BOM as protobuf binary.  [boolean] [default: false]
+      --proto-bin-file         Path for the serialized protobuf binary.  [default: "bom.cdx"]
+      --include-formulation    Generate formulation section with git metadata and build tools. Defaults to false.
+                                                                                              [boolean] [default: false]
+      --include-crypto         Include crypto libraries as components.                        [boolean] [default: false]
+      --standard               The list of standards which may consist of regulations, industry or organizational-specif
+                               ic standards, maturity models, best practices, or any other requirements which can be eva
+                               luated against or attested to.
+  [array] [choices: "asvs-5.0", "asvs-4.0.3", "bsimm-v13", "masvs-2.0.0", "nist_ssdf-1.1", "pcissc-secure-slc-1.1", "scv
+                                                                                         s-1.0.0", "ssaf-DRAFT-2023-11"]
+      --json-pretty            Pretty-print the generated BOM json.                           [boolean] [default: false]
+      --min-confidence         Minimum confidence needed for the identity of a component from 0 - 1, where 1 is 100% con
+                               fidence.                                                            [number] [default: 0]
+      --technique              Analysis technique to use
+  [array] [choices: "auto", "source-code-analysis", "binary-analysis", "manifest-analysis", "hash-comparison", "instrume
+                                                                                                   ntation", "filename"]
+      --auto-compositions      Automatically set compositions when the BOM was filtered. Defaults to true
+                                                                                               [boolean] [default: true]
+  -h, --help                   Show help                                                                       [boolean]
+  -v, --version                Show version number                                                             [boolean]
+```

packages/build-infra/lib/checkpoint-manager.mts

@@ -126,19 +126,12 @@ export function computeCacheHash(
  * @param {string} name - Checkpoint name (must be a CHECKPOINTS value).
  * @param {() => Promise<void>} smokeTest - Throws if the stage output is
  *   invalid.
- * @param {object} [options]
- * @param {string} [options.packageName]
- * @param {string} [options.artifactPath] - Informational; recorded in JSON.
- * @param {string} [options.binaryPath] - Informational; recorded in JSON.
- * @param {string | number} [options.binarySize] - Informational; recorded in
- *   JSON.
- * @param {string[]} [options.sourcePaths] - Inputs hashed into the cache key.
- * @param {string} [options.buildMode]
- * @param {string} [options.nodeVersion]
- * @param {string} [options.platform]
- * @param {string} [options.arch]
- * @param {string} [options.libc]
- * @param {string} [options.packageRoot]
+ * @param {CreateCheckpointOptions} [options] - Only `sourcePaths` and the
+ *   inherited platform fields (`buildMode`, `nodeVersion`, `platform`, `arch`,
+ *   `libc`) feed the cache key. `packageName` picks which checkpoint file is
+ *   written and `packageRoot` only shortens the logged path; `artifactPath`,
+ *   `binaryPath`, and `binarySize` are recorded in the marker for humans. None
+ *   of those five invalidate the checkpoint when they change.
  */
 export async function createCheckpoint(
   buildDir: string,

packages/build-infra/lib/platform-targets.mts

@@ -160,12 +160,8 @@ export interface PlatformTargetInfo {
  * @example
  *   parsePlatformTarget('darwin-arm64')
  *   // { platform: 'darwin', arch: 'arm64' }
- *
- * @example
  *   parsePlatformTarget('linux-x64-musl')
  *   // { platform: 'linux', arch: 'x64', libc: 'musl' }
- *
- * @example
  *   parsePlatformTarget('win-x64')
  *   // { platform: 'win32', arch: 'x64' }
  *

packages/cli/scripts/sea-build-utils/builder.mts

@@ -27,23 +27,17 @@ import { SOCKET_CLI_SEA_BUILD_DIR } from '../constants/paths.mts'
 // c8 ignore start
 /**
  * Generate SEA configuration file for Node.js single executable application.
- * Creates sea-config-{name}.json with blob output path and settings.
  *
- * Configuration includes: - Entry point, main file to bundle. - Output blob
- * path. - Code cache enabled for optimization. - Snapshot disabled for
- * compatibility. - No bundled assets, minimizes size.
- *
- * @example
- *   const configPath = await generateSeaConfig(
- *     '/path/to/dist/cli.js',
- *     '/path/to/socket-darwin-arm64',
- *   )
- *   // Returns: /path/to/sea-config-socket-darwin-arm64.json
+ * Writes `sea-config-<name>.json` naming the entry point to bundle and the blob
+ * output path, with the code cache on for faster startup, snapshots off (they
+ * would freeze build-time env values, and the CLI reads env at module load),
+ * and no bundled assets so the binary stays small.
  *
  * @param {string} entryPoint - Absolute path to the entry point file.
  * @param {string} outputPath - Absolute path to the output binary.
  *
- * @returns Promise resolving to absolute path of generated config file.
+ * @returns Promise resolving to the absolute config path, which is
+ *   `sea-config-<basename of outputPath>.json` beside that binary.
  */
 export async function generateSeaConfig(entryPoint, outputPath) {
   const outputName = path.basename(outputPath, path.extname(outputPath))
@@ -105,51 +99,19 @@ export async function generateSeaConfig(entryPoint, outputPath) {
 /**
  * Inject SEA blob and optional VFS assets into a Node.js binary using binject.
  *
- * This function performs the core SEA binary build step by:
- *
- * 1. Invoking binject to inject the SEA blob into the Node.js binary.
- * 2. Optionally embedding security tools via VFS compression (binject --vfs).
- *
- * Config-Based Blob Generation: Instead of pre-generating the SEA blob with
- * `node --experimental-sea-config`, binject reads the sea-config.json directly
- * and generates the blob automatically. This simplifies the API and reduces
- * build steps.
- *
- * VFS Compression (Optional): If vfsTarGz is provided, binject's --vfs flag
- * embeds the compressed tar.gz of security tools into the binary. This achieves
- * ~70% compression compared to Node.js SEA assets. If vfsTarGz is omitted,
- * --vfs-compat mode is used (no actual VFS bundling).
- *
- * @example
- *   await injectSeaBlob(
- *     'build-infra/build/downloaded/node-smol/darwin-arm64/node',
- *     'dist/sea/sea-config-socket-darwin-arm64.json',
- *     'dist/sea/socket-darwin-arm64',
- *     'socket-darwin-arm64-abc123',
- *     'build-infra/build/external-tools/darwin-arm64.tar.gz',
- *   )
- *   // Creates: dist/sea/socket-darwin-arm64 with CLI + compressed VFS
- *
- * @example
- *   await injectSeaBlob(
- *     'build-infra/build/downloaded/node-smol/linux-x64/node',
- *     'dist/sea/sea-config-socket-linux-x64.json',
- *     'dist/sea/socket-linux-x64',
- *     'socket-linux-x64-abc123',
- *   )
- *   // Creates: dist/sea/socket-linux-x64 with CLI only (no VFS)
+ * Binject reads sea-config.json directly and generates the blob itself, so
+ * there is no separate `node --experimental-sea-config` step. When `vfsTarGz`
+ * is given, its `--vfs` flag also embeds that compressed tar.gz of security
+ * tools, roughly 70% smaller than the equivalent Node.js SEA assets; without
+ * it binject runs in `--vfs-compat` mode and bundles the CLI alone.
  *
  * @param {string} nodeBinary - Path to the node-smol binary to inject into.
- * @param {string} configPath - Path to the sea-config.json file for
- *   config-based blob generation.
- * @param {string} outputPath - Path to the output SEA binary (may be same as
- *   nodeBinary).
- * @param {string} cacheId - Unique cache identifier for parallel builds
- *   prevents interference.
- * @param {string} [vfsTarGz] - Optional path to tar.gz file containing security
- *   tools for VFS bundling. If provided, security tools are compressed and
- *   embedded in the binary. If omitted, only the CLI code is bundled (no
- *   additional tools).
+ * @param {string} configPath - Path to the sea-config.json file.
+ * @param {string} outputPath - Path to the output SEA binary (may be the same
+ *   as nodeBinary).
+ * @param {string} cacheId - Unique cache identifier, so parallel builds do not
+ *   interfere with each other.
+ * @param {string} [vfsTarGz] - Optional tar.gz of security tools to embed.
  *
  * @returns Promise that resolves when injection completes.
  */

packages/cli/scripts/sea-build-utils/external-tools-install.mts

@@ -131,22 +131,22 @@ export async function downloadAndInstallTool(
     // Unlike other tools, Python requires its entire directory structure (stdlib, lib,
     // include directories) to function. The python-build-standalone package is a
     // complete, self-contained Python installation (~19 MB compressed).
-    //
+
     // Unix directory structure after extraction:
     // python/
     // ├── bin/           # Python executable and symlinks.
     // ├── lib/           # Standard library and site-packages.
     // ├── include/       # C headers for extension modules.
     // └── share/         # Documentation and other resources.
-    //
+
     // Windows directory structure after extraction:
     // python/
     // ├── python.exe     # Python executable at root.
     // ├── DLLs/          # Python DLLs and extensions.
     // ├── Lib/           # Standard library and site-packages.
     // ├── libs/          # Import libraries for linking.
     // └── include/       # C headers for extension modules.
-    //
+
     // We keep the entire python/ directory in the VFS for socket-basics to use.
     const pythonBinPath = normalizePath(
       path.join(