#277 [Feat] npm distribution: npx devprojex through platform binary packages

[Anonymous]

Originally created by: Avazbek22

Summary

The dnx channel (#276) serves the .NET world, but the audience that actually uses Repomix lives in the Node ecosystem — and for them "runs via npx, nothing to install" is the entire pitch. This issue puts DevProjex there on equal terms:

npx devprojex tree .

with no .NET requirement at all: the npm package carries a self-contained native binary per platform, so the only prerequisite is Node itself.

The npm name devprojex is free as of 2026-09-04. Repomix on npm is pure JavaScript (ESM, node>=22) whose cold start installs a dependency tree including ~24 MB of WASM grammars; a native binary distribution is a different — and honest — trade: bigger one-time download per platform, native startup and throughput afterwards. No performance claims in docs until we measure.

Packaging pattern

The industry-standard structure used by esbuild, Biome, Turborepo, and swc:

• One main package devprojex: a tiny JS bin launcher, no dependencies, no lifecycle scripts.
• N platform packages (@devprojex/cli-win32-x64, @devprojex/cli-linux-x64, @devprojex/cli-darwin-arm64, …), each carrying one self-contained binary plus os/cpu fields, wired into the main package as optionalDependencies.
• Package managers install exactly the one platform package matching the host; the launcher resolves it via require.resolve and spawns the binary, forwarding argv and the exit code.

Why this pattern and not a postinstall download: it survives --ignore-scripts (common in hardened CI), works behind corporate proxies and private registry mirrors, and keeps the whole payload inside the registry with provenance attached.

Payload source: the headless terminal binaries from [#276] (CLI + TUI + MCP, no GUI). Platform binary packages in this size class are normal on npm — Biome's linux-x64 CLI package is ~64 MB unpacked, and the practical registry limit sits far higher (~200 MB per tarball).

Platform matrix

win32-x64, win32-arm64, linux-x64, linux-arm64, darwin-x64, darwin-arm64 — mirroring the RID set in [#276]. Decide during implementation whether musl (Alpine) variants are worth a follow-up; document the gap either way.

Launcher requirements

• Clear, actionable error when no platform package is present (--omit=optional installs, unsupported platform): name the supported platforms and the alternative channels (dnx, GitHub releases).
• No network access, no telemetry, no version-check calls — the launcher only resolves and spawns.
• Signals and stdio pass through untouched so MCP stdio framing and TUI interactivity are not disturbed.

Publishing

• GitHub Actions with npm trusted publishing (OIDC): permissions: id-token: write, npm CLI ≥ 11.5.1, no long-lived token in secrets; provenance attestations are generated automatically.
• Ordering discipline mirrors the NuGet flow: all platform packages first, main package last, identical versions.
• Wire into the same release pipeline stage as [#276] so one release publishes both channels or fails atomically.

Known ecosystem pitfalls (document, not solve)

• npm regenerating package-lock.json with node_modules present can prune other platforms' optional deps (npm/cli#7961, [#8320]) — affects projects that add devprojex as a dependency, not npx one-shot runs. A short troubleshooting note in the docs is enough.
• pnpm/Yarn Berry users who need multi-platform lockfiles use their supportedArchitectures mechanisms; nothing for us to do beyond mentioning it.

Non-goals

• No JavaScript reimplementation of any DevProjex functionality — the npm package is a launcher, nothing more.
• No postinstall downloads from GitHub releases or any other out-of-registry source.
• No GUI in the npm channel.

Dependencies

• Requires the headless self-contained binaries from [#276]. The npm name should be reserved with a placeholder publish before this ships in full.

Acceptance criteria

• npx devprojex tree . works on clean Windows, Linux, and macOS machines with only Node installed — no .NET runtime or SDK present.
• npx devprojex mcp --root . serves MCP over stdio through the launcher without framing issues.
• Installation with --ignore-scripts works; installation with --omit=optional fails with the documented actionable message.
• Per-platform package sizes are reported in the release notes.
• Publishing runs through trusted publishing with provenance; platform-first ordering is enforced by the pipeline.
• README and Docs/CommandLine.md present the three install-free channels side by side: npx devprojex, dnx devprojex, and direct binaries.

[Anonymous]

Originally posted by: Avazbek22

Before this channel first publishes, it needs the completeness gate and functional smoke required by [#278] — each npm platform package joins the same payload-manifest validation as the existing channels.