spike(npm): prototype npx stash proxy distribution

[coderdan]

Spike / draft implementing CIP-3824. Stacked on #397 (dan/cli-connection-flags); the review diff is limited to npm/.

Prototypes distributing CipherStash Proxy through npm so it can be launched with:

npx stash proxy --database-url postgres://user:pass@host:5432/db
npx stash proxy --psql --database-url postgres://user:pass@host:5432/db

Distribution design

• A thin pure-JavaScript stash meta package resolves and launches the correct prebuilt Proxy binary while forwarding argv, stdio, exit status, and common termination signals.
• Four os/cpu-filtered optional platform packages cover macOS and Linux on arm64 and x64.
• The macOS arm64 staging path applies an ad-hoc signature and fails if signing does not succeed.
• npm/build-binaries.sh builds and stages the current host binary.
• npm/release-workflow.example.yml sketches a four-target build/publish matrix, including a working Linux arm64 cross setup.

--psql workflow

• Starts Proxy and waits for its reported listen address, including an OS-assigned fallback port.
• Launches system psql, or a pure-JavaScript SQL shell when psql is unavailable.
• Uses a cyan stash:<db>=> prompt on interactive terminals.
• Propagates connection URL, individual long/short flags, --flag=value forms, positional database name, and environment fallbacks using the same CLI-over-URL-over-environment precedence as Proxy.

Review fixes

• Fixed the demo's expected-failure assertion so set -e no longer terminates it prematurely.
• Extracted connection interpretation from the launcher and added dependency-free unit tests.
• Preserved child signal termination semantics and added SIGQUIT forwarding.
• Rebased onto the reviewed feat(cli): connection flags + DX (quiet logging, random port, best-effort TLS) #397 head and added required DCO sign-offs to all seven commits.

Validation

• node --check for all launcher modules.
• npm test: 3/3 connection-propagation tests pass.
• bash -n npm/build-binaries.sh npm/demo.sh.
• npm pack --dry-run for the meta package and all four platform packages.
• Full macOS arm64 proof: release build, ad-hoc signing, local npm install, correct platform-package resolution, npx version/help passthrough, and exit-code validation.

Status / decision

This remains a non-publishable prototype: packages are private and versioned 0.0.0-prototype; no release workflow is active and no platform package has been published.

• Decide whether to productionize this distribution channel.
• If yes, wire the example workflow into release CI and define npm access plus synchronized package versioning.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 47445073-8e8f-45e3-832e-7997c0071df3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dan/npx-stash-proxy-prototype

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}