Apply automatic formatting and linting fixes:
- Sort imports alphabetically across multiple files
- Fix trailing whitespace and indentation
- Update shadow/runner.mts to use getDefaultApiToken() for consistency
- Format object destructuring and function calls

No functional changes, only code style improvements.

Add --reach-concurrency and --reach-disable-analysis-splitting flags
to control Coana reachability analysis behavior. These flags are now
supported across all commands that perform reachability analysis:
scan create, scan reach, and CI workflows.

- reachConcurrency: Maximum concurrent analysis runs (default: 1)
- reachDisableAnalysisSplitting: Limit to 1 analysis per workspace

Remove automatic fallback to public API token in alerts utility.
The token should be explicitly passed or inherited from the SDK
configuration, which properly respects SOCKET_CLI_API_TOKEN.

Remove tilde prefix from Coana version specification to ensure
exact version matching instead of allowing patch updates. This
provides more predictable behavior and better reproducibility
for reachability analysis.

Refactor PR creation to check for existing open PRs instead of branch
existence, preventing the bug where PRs would only be created once.

Key changes:
- Check for open PR existence before creating new PR
- Clean up stale branches (branch exists but no open PR)
- Validate GitHub token before git operations to fail fast
- Use typed discriminated union for PR creation error handling
- Proper branch cleanup based on success/failure scenarios

Branch lifecycle management:
- Remote branches are sacred when a PR exists (kept for merge)
- Remote branches are disposable when no PR exists (cleaned up)
- Local branches cleaned up after successful PR creation
- Both remote and local branches cleaned up on failure

Created new branch-cleanup.mts module to centralize branch lifecycle
management with clear documentation of cleanup semantics.

- Extract package deduplication logic to getUniquePackages() helper
- Extract env var checking logic to checkVar() helper
- Extract temp file cleanup logic to cleanupTempFile() helper

…t SHA

Migrate externalTools from flat format to structured format matching
socket-sbom-generator and socket-btm patterns. Add descriptions, types,
and metadata for each tool.

Changes:
- Restructure externalTools with description, type, package, and version
- Add @cyclonedx/cdxgen to externalTools (version 11.11.0)
- Update @coana-tech/cli from 14.12.76 to 14.12.90
- Remove @coana-tech/cli from devDependencies (now in externalTools only)
- Remove catalog entries for @coana-tech/cli and @cyclonedx/cdxgen
- Update esbuild-shared.mjs to read structured format
- Pin exact versions (remove ~ prefix) for coana and cdxgen
- Rename socketcli to socketsecurity, pythonBuildTag to buildTag

Tool types:
- npm: @coana-tech/cli, @cyclonedx/cdxgen
- pypi: socketsecurity (socket-python-cli)
- github-release: python (python-build-standalone)
- standalone: sfw (Socket Firewall)

- Fixed bug where --limit flag was ignored in local mode (line 186)
  - Was passing full ghsas array instead of limited ids array
  - Now correctly passes only the first N GHSAs as specified by --limit
- Add unit tests for --limit behavior verification
  - 6 unit tests with mocks/spies verify actual business logic
  - Tests verify correct number of GHSAs passed to coana CLI
  - Tests cover local mode, limit adjustment, and edge cases

Fixes issue where 'socket fix --limit 1' would process all
vulnerabilities instead of limiting to 1.

Ported from v1.x branch (jdalton/test-fix-limit-id).

- Update @coana-tech/cli from 14.12.90 to 14.12.94
- Fix import path for DOT_SOCKET_DOT_FACTS_JSON in coana-fix.mts
- Add 3 PR mode tests for --limit flag behavior in handle-fix-limit.test.mts
  - Test limit enforcement in PR mode
  - Test limit adjustment based on existing open PRs
  - Test behavior when existing PRs exceed limit
- Test coverage increased from 6 to 9 tests (+50%)

- Create shared socket-btm-releases utility module
- Dynamically fetch latest releases from GitHub API
- Support env var overrides (SOCKET_BTM_*_TAG)
- Cache downloads in build/.cache instead of ~/.socket
- Add extract-node-smol.mjs for on-demand SEA binary extraction
- Add extract-models.mjs for AI models (MiniLM-L6-v2, CodeT5)
- Refactor extract-yoga-wasm.mjs to use shared utilities
- Update build.mjs to extract yoga and models (node-smol on-demand only)
- Rename SOCKET_CLI_NODE_DOWNLOAD_URL to PREBUILT_NODE_DOWNLOAD_URL
- Default to socket-btm smol binaries instead of nodejs.org archives
- Add ES module export to yoga-sync.mjs for esbuild compatibility

Standardize property order in all package.json files for consistency.

Changes:
- Reorder properties according to standard order:
  name, version, description, private, license, main, bin, type,
  exports, files, os, cpu, scripts, dependencies, devDependencies,
  peerDependencies, optionalDependencies, engines, repository,
  author, homepage, bugs, keywords, publishConfig, ...
- Run 'npm pkg fix' on all packages to apply npm's own fixes
- 12 packages normalized, 13 packages fixed

Standard order improves:
- Readability: Important metadata appears first
- Consistency: All packages follow same structure
- Maintainability: Easier to spot differences in diffs

… in workflows

Separate external tool configurations from package.json into dedicated
external-tools.json files for better organization and maintainability.
Add workflow documentation referencing these files as source of truth.

Changes:
- Create packages/cli/external-tools.json for CLI-specific tools
  (@coana-tech/cli, @cyclonedx/cdxgen, python, socketsecurity, sfw)
- Create packages/build-infra/external-tools.json for core build tools
  (cmake, emsdk, gh, ninja, python, rust)
- Update esbuild-shared.mjs to read from external-tools.json
- Remove externalTools field from both package.json files
- Fix SpawnNodeOptions.ipc type to include | undefined for exactOptionalPropertyTypes
- Update analytics test snapshots with current dates
- Update build-infra external-tools.json versions to match workflow usage:
  - emsdk: 3.1.69 -> 4.0.18
  - python: 3.10.18 -> 3.11
- Add "Version from packages/build-infra/external-tools.json" comments to workflows:
  - build-wasm.yml: emsdk and python-version references
  - build-sea.yml: emsdk cache key and python-version references

…achability (Coana) CLI

- Increase CVE to GHSA mapping cache TTL from 5 minutes to 30 days
  since these conversions are permanent and never change
- Improve error messaging for rate limit and network errors (EPIPE,
  ECONNRESET) to provide clearer guidance to users
- Add detection for common rate limit error patterns to distinguish
  them from generic API errors

This addresses rate limit errors that were showing as generic "Socket
API error: write EPIPE" messages without helpful context for users.

- Format all .mjs and .mts files with biome
- Add eslint.config.js from v1.x branch
- Format 66 files across packages and scripts

Update pnpm/action-setup SHA to official v4.2.0 release (SHA: 41ff72655975bd51cab0327fa583b6e92b6d3061)

The self-update feature's bootstrap binary updating was broken due to
incorrect API usage. getIpcStubPath() returns a JSON file path for IPC
data, not the bootstrap binary path.

Changes:
- Pass bootstrap binary path via IPC handshake in bootstrap wrapper
- Add getBootstrapBinaryPath() to retrieve path from handshake
- Fix updateBootstrapBinary() to use correct binary path
- Rename all "stub" terminology to "bootstrap binary" for clarity
- Remove broken test files for non-existent features

The bootstrap wrapper now passes its own binary path via the IPC
handshake extra field, allowing self-update to correctly update both
the main CLI binary and the bootstrap wrapper binary.

test(cli): fix analytics test import paths and remove dead tests
- Fix output-analytics.test.mts to import from correct source paths
- Remove intl-stub.test.mts (no source implementation)
- Remove update store tests (no store.mts implementation)

Update Coana CLI external tool version from 14.12.94 to 14.12.103.

…rm-reachability-analysis

Upload manifest files relative to target directory to ensure Coana
resolves SBOM manifest files relative to the correct path.

In coana-fix, pass cwd as the relative path base.
In perform-reachability-analysis, pass path.resolve(cwd, analysisTarget)
as the relative path base.

- Use case-insensitive error matching for more reliable detection
- Add more specific status code patterns (status: 403, status code 403)
- Express 30-day duration as readable calculation (30 * 24 * 60 * 60 * 1000)
- Remove redundant inline comment
- Rename variable for clearer intent (isGitHubRateLimit -> isRateLimitOrNetworkError)

Update GitHub Actions across all workflows:
- actions/checkout: 4.2.2/5.0.0 -> 6.0.1
- actions/cache: 4.2.0 -> 4.3.0
- actions/setup-node: 4.1.0/4/5.0.0 -> 6.1.0
- actions/upload-artifact: 4.x -> 5.0.0
- actions/download-artifact: 4.x -> 6.0.0
- actions/github-script: 7 -> 8.0.0

All SHAs verified against GitHub releases.

- Update import paths for dlx modules split
- Fix type narrowing issues in config.mts for improved type safety

…st release

Only check commits after the latest published release tag instead of scanning
entire history. This prevents false positives from old commits with AI
attribution that are already on origin/main from merged PRs.

Changes:
- Find latest v* tag merged into branch being pushed
- Only scan commits after that tag
- Fall back to full history if no release tags exist
- Applies to both new branches and existing branches

Benefits:
- No false positives from historical commits
- Faster push validation
- Still blocks new AI attribution in unpublished code

…ples

Replace hardcoded personal paths with environment variables and make API
key examples clearly non-functional to prevent pre-push hook failures.

Changes:
- Use $HOME instead of /Users/jdalton in activate-build-env.sh
- Use relative paths in docs/performance/performance-ci.md
- Replace sktsec_test_* patterns with clearly fake placeholder text

Replaced globalThis.process with direct process import for consistency
and clarity.

Changes:
1. Added 'import process from node:process'
2. Changed globalThis.process?.stdout?.isTTY to process.stdout?.isTTY
3. Affects 2 functions: showUpdateNotification, scheduleExitNotification

Rationale:
- Consistent with rest of codebase (uses direct process import)
- Removes unnecessary indirection
- Makes mocking easier in tests
- Standard Node.js pattern

All checks passing: lint ✓, type ✓

Replace all 'as unknown as' type assertions in command files with typed
interfaces for better type checking and maintainability.

Changes:
- Add typed flag interfaces to 18 command files
- Replace 'cli.flags as unknown as { ... }' with named interfaces
- Eliminate double type assertions (as unknown as T)
- Improve IDE autocomplete and compile-time type checking

Files updated:
- Analytics, audit-log, config-auto, fix, login
- Manifest commands (cdxgen, conda, gradle, kotlin, scala)
- Pycli, repository-list, sfw
- Scan commands (create, diff, github, reach, report)

This addresses architectural debt documented in .claude/tmp-architectural-notes.md
without changing runtime behavior.

Fix integer overflow, path traversal, and JSON validation issues found in
comprehensive quality scan.

High Priority:
- Add 60s cap to exponential backoff in update checker to prevent overflow
  (src/utils/update/checker.mts:260)

Medium Priority:
- Cap exponential backoff in GHSA tracker lock acquisition to 10s max
  (src/commands/fix/ghsa-tracker.mts:115)
- Add safe attempt bounds in GitLab provider retry logic before calculation
  (src/utils/git/gitlab-provider.mts:89)
- Improve path traversal check with normalization for cdxgen output validation
  (src/commands/manifest/run-cdxgen.mts:140)

Low Priority:
- Add JSON structure validation for analytics app stdin data
  (src/commands/analytics/analytics-app-cli.mts:26)
- Add array validation for GHSA IDs parsed from coana output
  (src/commands/fix/coana-fix.mts:307)

Security improvements:
- Prevent integer overflow in exponential backoff (3 locations)
- Strengthen path traversal prevention with path.normalize()
- Add runtime type checking for external tool JSON outputs

Note: Event emitter cleanup in conda converter was already properly
implemented (all handlers call cleanup function).

Improve code quality with idiomatic patterns and better validation.

Changes:
- Replace index-based loop with for...of in coana GHSA processing
  (src/commands/fix/coana-fix.mts:353) - more idiomatic and type-safe
- Add UTF-8 validation for base64-decoded config data
  (src/utils/config.mts:137) - detect invalid encoding earlier
- Use UTC timezone for scan list dates for consistency
  (src/commands/scan/output-list-scans.mts:48) - same date display globally

Benefits:
- Eliminates non-null assertion operator in loop
- Provides clearer error messages for config encoding issues
- Ensures consistent date display across timezones

Add optional chaining to getHighestEntryIndex to match the defensive pattern
used in sibling function getLowestEntryIndex.

Issue:
- getLowestEntryIndex uses optional chaining: getEntryIndexes()?.[0]
- getHighestEntryIndex did not: getEntryIndexes().at(-1)
- Inconsistency creates potential future vulnerability if getEntryIndexes
  implementation changes to return null/undefined

Fix:
- Add optional chaining: getEntryIndexes()?.at(-1) ?? -1
- Now both functions have consistent defensive programming

Risk mitigation:
- Prevents potential "Cannot read property 'at' of undefined/null" crash
- Maintains consistent null safety with sibling function
- Defensive programming for future code changes

Location: src/commands/optimize/update-manifest-by-agent.mts:46

Add validation for negative time deltas (future timestamps) to prevent
incorrect time formatting.

Issue:
- Function did not handle case where isoTimeStamp represents a future time
- When timeStart > timeEnd, delta becomes negative
- Negative deltas would match first condition (delta < 60*60*1000)
- Result: Future timestamps displayed incorrectly (e.g., "60 in 60 min")

Fix:
- Add check: if (delta < 0) return isoTimeStamp.slice(0, 10)
- Future timestamps now fall back to ISO date format (YYYY-MM-DD)
- Prevents incorrect relative time formatting

Example:
- Before: Timestamp 2 hours in future → "120 in 120 min" (wrong)
- After: Timestamp 2 hours in future → "2026-02-24" (correct fallback)

Risk mitigation:
- Prevents confusion in audit trails and scheduled operations
- Ensures consistent time display behavior
- Matches fallback behavior for very old timestamps (>7 days)

Location: src/utils/home-cache-time.mts:13-16

TypeScript requires the double cast pattern ('as unknown as SpecificType')
when converting between types that don't structurally overlap. MeowFlags
doesn't overlap with the specific flag interfaces, so direct casts fail
with TS2352 errors.

Affected command files (23 assertions across 18 files):
- analytics, audit-log, config-auto, fix (2x), login
- manifest: cdxgen, conda (2x), gradle, kotlin, scala
- pycli, repository-list
- scan: create (3x), diff, github (2x), reach, report
- sfw

This reverts the Round 16 type safety improvement while keeping the
interface definitions for documentation purposes.

Move @socketsecurity/cli from dependencies to devDependencies since it's
only needed during build time to access source files. Remove duplicate
@sentry/node from devDependencies.

Correct structure:
- dependencies: @sentry/node (runtime requirement via require())
- devDependencies: @socketsecurity/cli (build-time source access),
  build-infra, esbuild

The workspace:* dependency would fail to resolve when published to npm,
so it must be a devDependency.

…ents

- Changed TODO comments to PLANNED ENHANCEMENT to clarify status
- Added references to socket-btm/docs/vfs-configuration-plan.md design doc
- Noted that VFS APIs (getAsset, getAssetKeys) already exist in node-smol
- Referenced workaround location (line 296-302) for missing dependencies
- Clarified these are optimizations that don't block current functionality

These comments document a known limitation where VFS extraction currently
handles only single binaries, not full directory trees with dependencies.
The workaround warns users when this limitation is encountered. Full
directory extraction is fully designed and ready to implement when needed.

- Add Phase 2: Update Dependencies to quality-scan skill
- Runs `pnpm run update` across socket-btm, socket-sbom-generator, socket-cli, and ultrathink
- Tracks packages updated per repository in scan reports
- Update pnpm ^10.29.3 → ^10.30.1
- Update fast-xml-parser ^5.3.5 → ^5.3.7
- Update lru-cache ^11.0.2 → ^11.2.6
- Update overrides: qs >=6.14.2 → >=6.15.0, glob >=13.0.3 → >=13.0.6

…ot rationale

- Document useCodeCache provides ~13% faster startup (~22ms improvement)
- Explain why useSnapshot is incompatible with socket-cli
- socket-cli accesses ~70 env vars at module load time (HOME, SOCKET_CLI_API_TOKEN, etc.)
- Snapshots would freeze build-time env values, breaking runtime configuration
- Note that code cache + bundling provides ~25-30% startup improvement without restrictions

This clarifies the performance strategy and why snapshots can't be used.

- Use process.smol.mount() API for extracting tools from VFS with full dependencies
- Extract complete npm package directories (node_modules/@package/name/)
- Remove manual getAsset() + fs.writeFile() workaround
- Automatically extract all production dependencies and subdirectories
- Preserve file permissions and directory structure
- No longer warn about missing dependencies (they're now extracted)

For npm packages:
- Mount entire package directory: /snapshot/node_modules/@cyclonedx/cdxgen
- Includes all production dependencies from Arborist
- Supports cdxgen, coana, socket-patch, synp

For standalone binaries:
- Mount single binary file: /snapshot/sfw
- Handles GitHub release binaries

node-smol now supports full directory tree extraction with the mount()
API, eliminating the previous limitation documented in TODOs.

See socket-btm/docs/vfs-runtime-api.md for full documentation.

- Update pnpm from 10.30.1 to 10.30.2
- Update lru-cache from ^11.0.2 to ^11.2.6
- Update fast-xml-parser from ^5.3.5 to ^5.3.7
- Fix pre-push hook syntax: replace process substitution with pipe for better shell compatibility

The pre-push hook now uses `git rev-list | while read` instead of
`while read < <(git rev-list)` to avoid syntax errors in some shell environments.

- Replace socket-btm context with socket-cli context
- Update package references (@socketsecurity/cli, not node-smol-builder)
- Update file paths (packages/cli/src/ instead of packages/*/src/)
- Update technology stack (TypeScript/React/Ink, no C/C++)
- Update concerns (CLI commands, npm wrapping, VFS extraction)
- Update examples to match socket-cli patterns
- Add socket-cli specific patterns (Socket API, GitHub API, meow CLI)
- Update known false positives (VFS process.smol.mount, package name 'socket')
- Remove socket-btm specific patterns (binary compilation, patches)

All agent prompts now correctly target socket-cli codebase with appropriate
context, examples, and quality guidelines.

Fix all issues identified in comprehensive quality scan:

Logic fixes:
- dlx/spawn: Handle empty pip version specifier edge case (^)

Workflow fixes:
- pre-push: Fix AI attribution detection subshell bug
- package.json: Remove trailing -- from cover script

Documentation fixes:
- pre-commit: Document .env.precommit as optional
- build-guide: Correct Node.js version for published CLI (18.0.0)
- README: Add requirements and clarify dev vs published packages

Cache behavior documentation:
- config: Document retry exhaustion behavior as intentional
- update: Clarify timestamp capture timing is intentional

…pre-push

The process substitution syntax `< <(...)` is bash-specific and causes
syntax errors when Git invokes the hook with sh on some systems.

Changed from:
  while IFS= read -r commit_sha; do
    ...
  done < <(git rev-list "$range")

To portable sh-compatible for loop:
  for commit_sha in $(git rev-list "$range"); do
    ...
  done

This solution:
- Works with any POSIX shell (sh, bash, dash, etc.)
- Avoids subshell creation (unlike pipe)
- Correctly propagates ERRORS variable to parent scope
- Fixes AI attribution detection that was failing silently

The pre-push hook was checking all commits since the last release tag
(v0.1.2), which included 4914 commits. This blocked pushes even when
problematic commits were already on remote.

Changed existing branch logic from:
  range="$latest_release..$local_sha"  # All commits since v0.1.2

To:
  range="$remote_sha..$local_sha"  # Only new commits being pushed

This prevents blocking pushes for old commits that already made it to
remote, while still catching new commits with AI attribution.

Fixed isStricterPolicy() logic that incorrectly determined policy precedence when aggregating alerts. The function was returning false for WARN/MONITOR/IGNORE comparisons when it should return true, causing lower-severity alerts to incorrectly override higher-severity ones.

Impact: Users could miss critical security violations because WARN alerts were being replaced by MONITOR or IGNORE policies in scan reports.

Also documented known race condition in update cache where concurrent CLI invocations may perform duplicate npm registry requests during TTL expiration. This is an acceptable tradeoff for simplicity as it only wastes resources without corrupting data.

- Updated README coverage badge (41.97% → 41.85%)
- Applied zizmor security fixes: use environment variables for workflow inputs
  to prevent template injection vulnerabilities (8 fixes in publish-socketbin.yml)
- Added concurrency controls to prevent duplicate workflow runs:
  - CI workflow: cancel in-progress runs for PR branches, preserve for main
  - Publishing workflows: never cancel (prevent interrupted releases)
- Added job name and permission documentation in provenance workflow

These changes improve security posture and resource efficiency based on
quality scan findings from zizmor security scanner.

Added missing sfw (Socket Firewall) tool to SEA binary builds:

- Updated external-tools.json: Changed sfw from standalone to github-release
  type with SocketDev/sfw-free repository and v1.6.0 version
- Added sfw to all platform mappings (8 platforms supported):
  - darwin-arm64, darwin-x64: Native binaries
  - linux-arm64, linux-x64: Native glibc binaries
  - linux-arm64-musl, linux-x64-musl: Native musl binaries
  - windows-arm64, windows-x64: x64 binaries (ARM64 uses emulation)
- Enhanced downloads.mjs to handle standalone binaries that don't require
  extraction (sfw binaries are not compressed, unlike other tools)

This fixes "File not found in VFS: /snapshot/sfw" error when running
socket-cli SEA binaries with npm/npx/pnpm/yarn commands.

Previous behavior:
- sfw declared in EXTERNAL_TOOLS but never bundled into VFS
- SEA binaries failed with VFS extraction error
- Regular node cli.js worked (downloaded sfw via dlx)

New behavior:
- sfw downloaded from SocketDev/sfw-free releases during SEA build
- sfw bundled into VFS alongside other security tools
- SEA binaries can extract and use sfw from embedded VFS

Sources:
- https://github.com/SocketDev/sfw-free
- https://docs.socket.dev/docs/socket-firewall-free

Socket Firewall (sfw) was failing to extract from VFS in SEA binaries because:
1. node-smol VFS API requires all files under /snapshot/node_modules/ for security
2. sfw was packaged at VFS root, causing "Invalid VFS path" errors
3. Extracted binaries lacked executable permissions

Changes:
- Update downloads.mjs to package sfw in node_modules/@socketsecurity/sfw-bin/
- Add TOOL_STANDALONE_PATHS mapping for standalone binaries under node_modules
- Create getToolFilePath() helper to centralize path resolution
- Add chmod 0o755 for extracted standalone binaries on Unix
- Remove unimplemented npm package tools from EXTERNAL_TOOLS (cdxgen, coana, etc.)

VFS structure now:
  node_modules/@socketsecurity/sfw-bin/sfw  (standalone binary)
  node_modules/@cyclonedx/cdxgen/           (future: npm packages)

Verified:
- ✓ SEA binary builds successfully with sfw in VFS
- ✓ socket npm whoami command extracts and executes sfw correctly
- ✓ Socket Firewall protection active for npm commands

Replace node:sea.getAsset() with process.smol.mount() for extracting
socket-basics security tools (Python, Trivy, TruffleHog, OpenGrep) from
the VFS filesystem embedded in SEA binaries.

process.smol.mount() handles caching, locking, and extraction automatically,
simplifying the code and eliminating manual path management. The mount API
extracts files to its own managed cache directories and returns the paths.

Changes:
- Remove node:sea.getAsset() and createRequire imports
- Use process.smol.mount() for all tool extractions
- Simplify extractBasicsTools() by removing manual cache/lock logic
- Update validation to use paths returned by mount()
- Use logger.group/success for better output formatting

Signed-off-by: lelia <lelia@socket.dev>

Signed-off-by: lelia <lelia@socket.dev>