Skip to content

Repository navigation

native-development.md

Latest commit

 

History

History
119 lines (89 loc) · 4.95 KB

native-development.md

File metadata and controls

119 lines (89 loc) · 4.95 KB
Raw

Native development and testing

Sockeye is a C++ command-line program with one Objective-C++ file for macOS frameworks. Node.js scripts build and test it so the repository keeps the same developer commands as the rest of the fleet.

Source layout

Path Purpose
src/sockeye/*.cc Portable C++ policy, process, terminal, and memory code.
src/sockeye/keychain-macos.mm macOS Keychain and LocalAuthentication bridge.
CMakeLists.txt Native compiler, linker, warning, and local signing settings.
scripts/repo/build.mts Canonical CMake entry point and output-path owner.
scripts/repo/test.mts Builds first, then starts the fleet Vitest runner.
test/repo/integration/*.test.mts Tests the compiled CLI as a child process.

There is no test/runtime, test/native, or test/cpp top-level tier. The test folder describes what kind of test it is, not which language produced the program:

  • test/repo/unit is for isolated behavior.
  • test/repo/integration is for process and operating-system boundaries.
  • test/repo/e2e is for complete release or installer flows.

If a future C++ test executable is useful, its source belongs below the matching test/repo/<kind>/native area. A Vitest test still builds and starts it. This keeps one test command, one result format, and one CI discovery path.

Build

pnpm run build

Development output uses this shape:

build/dev/darwin-arm64/out/Final/sockeye

BUILD_MODE=prod pnpm run build creates an optimized release-shaped build. It does not make the binary publishable; signing and notarization are separate release gates.

Test

pnpm run test

The noninteractive suite stops before Touch ID and Keychain access. It checks the command contract, rejects ambiguous manifests, and uses a canary value to make sure errors do not echo secret input.

Manual security tests must use throwaway credentials. Never put a real credential value in a fixture, snapshot, command argument, or test log.

Native coverage

Run all enabled coverage collectors with pnpm run cover. The native collector uses the fleet-pinned LLVM archive for C++ and Objective-C++ coverage. Clang, Clang++, llvm-profdata, and llvm-cov must have matching versions. Coverage builds use the macOS SDK and shared CMake instrumentation. Vitest runs the instrumented binaries and addon through noninteractive tests. llvm-profdata merges execution profiles, and llvm-cov exports LCOV reports.

The cumulative report combines JavaScript and native covered and total counts. Type coverage remains separate. .cache/fleet/coverage/coverage-aggregate.json records the cumulative result and each language's measurement unit. cover.cumulativeCoverageThreshold in .config/repo/socket-wheelhouse.json enforces the cumulative minimum.

The native inventory includes src/sockeye, the keychain addon, and the macOS keystore implementation. Reports live under .cache/fleet/coverage/lanes/. Tests replace protected framework operations with test doubles. Native coverage does not establish that attended Touch ID or enrollment checks passed.

SVG assets

GitHub renders repository SVG files more reliably than large inline SVG blocks. Keep repository-facing art under assets/repo/. The fleet preset owns assets/repo/coverage.svg; Sockeye owns assets/repo/logomark.svg and assets/repo/logomark-inverse.svg. Reference these files from Markdown or HTML. Run the pinned SVGO pass to optimize both glyph variants:

pnpm run optimize:svg

test/repo/unit/svg-assets.test.mts checks that each committed glyph is already an SVGO fixpoint. A second optimization pass must produce the same markup.

Native quality checks

The CMake build treats warnings as errors and enables stack protection. Run the two sanitizer modes separately because they catch different bug classes:

pnpm run test:asan
pnpm run test:ubsan

ASan looks for invalid memory access and lifetime bugs. UBSan looks for C++ operations whose behavior is undefined. Each command rebuilds both the CLI and the small native input-policy test with the selected sanitizer, then Vitest starts the native test executables.

The fuzz target feeds arbitrary byte strings through the credential-name, terminal-input, approval-display, and canonical manifest-field policies:

pnpm run fuzz

The local budget is 60 seconds. A release candidate should run at least 15 minutes with SOCKEYE_FUZZ_SECONDS=900 pnpm run fuzz and record the command, compiler version, duration, and final execution count in the release evidence. Fuzzing these pure byte-policy functions does not test Keychain UI behavior or the final executable path race; those have separate release gates.