feat(distribution): support npm install for the native ProjectAtlas CLI

[styler-ai]

Why

ProjectAtlas v0.4.0 ships verified native Rust binaries, PowerShell/POSIX runtime installers, Cargo installation, and Codex plugin installation, but it does not ship a ProjectAtlas npm package. A familiar global install such as npm install -g <projectatlas-package> would make the native CLI accessible to users who already install coding-agent CLIs through npm and do not have Rust/Cargo installed.

This should reuse the existing release assets and installer guarantees. npm should be a thin distribution adapter for the same versioned native runtime, not a second ProjectAtlas implementation or an independent source of release truth.

What Changes

• Publish an official npm package that exposes the native projectatlas command on supported platforms.
• Reuse the existing release version, platform/architecture mapping, native archives, SHA-256 verification, runtime identity/version guard, and stale-shim handling wherever possible.
• Keep one authoritative native runtime per ProjectAtlas release; the npm layer downloads or selects that exact runtime instead of compiling or reimplementing ProjectAtlas.
• Make npm install -g ... and the supported npx ... path resolve the package-owned, version-matched runtime predictably.
• Integrate npm packaging and publication into the existing release workflow with provenance, dry-run package inspection, and supported-OS installation smoke tests.
• Document install, upgrade, uninstall, proxy/offline failure behavior, and how npm installation coexists with the Codex plugin, Cargo, and direct release installers.

Capabilities

New capability

• npm distribution for the native ProjectAtlas CLI.

Existing capabilities reused

• Versioned native release assets.
• Platform and architecture selection.
• Release checksum verification.
• Runtime identity and version validation.
• PATH/shim conflict detection.
• Project-local projectatlas init after installation.

Architecture Diagrams

• Plugin packaging and runtime delivery

Release Scope

Backlog feature with no release milestone yet. It is explicitly outside the bugfix-only v0.4.1 stabilization release. Promote it only after the v0.4 line is stable and an OpenSpec change owns implementation tasks.

Likely touch points include the release workflow, a minimal npm package surface, and the existing PowerShell/POSIX installer contract. Reuse or extract the smallest shared release-asset contract; do not duplicate installer policy in unrelated implementations.

Acceptance Criteria

• The official package name and publisher ownership are documented and verifiable.
• npm pack contains only the intended launcher/metadata/install surface and no repository secrets, local state, databases, or benchmark artifacts.
• A clean global npm install works without Rust/Cargo on every platform for which ProjectAtlas publishes a native runtime.
• The installed projectatlas --version and projectatlas --format json runtime-info match the npm package version and report the native ProjectAtlas runtime.
• Runtime acquisition uses the existing release assets and fails closed on a missing asset, unsupported platform, version mismatch, or checksum mismatch.
• Reinstall and upgrade replace only npm-owned/runtime-owned state without deleting project-local .projectatlas data, approved purposes, configuration, or unrelated shims.
• Uninstall removes only npm-owned launcher/runtime state and leaves project databases intact.
• npm, Codex-plugin, Cargo, and direct-release installation paths can coexist or report an actionable PATH conflict without silently launching a stale version.
• The release workflow publishes npm only after the matching native assets and integrity metadata exist, and cross-platform install smokes verify the published package.
• README and installation documentation explain npm install, upgrade, uninstall, and the separate projectatlas init step.

Non-Goals

• Do not rewrite the Rust CLI or MCP server in JavaScript/TypeScript.
• Do not create a separately compiled npm-specific ProjectAtlas binary.
• Do not make npm a runtime dependency for plugin, Cargo, or direct-release users.
• Do not mutate or initialize the current project during a global npm package install; project setup remains an explicit projectatlas init.
• Do not include this feature in v0.4.1.
• Do not run the manual long navigation benchmark for ordinary npm packaging verification.

Pre-Mortem

Likely failure modes:

• npm metadata and GitHub release versions drift, exposing the wrong native runtime.
• Platform selection or archive naming is copied into multiple places and diverges.
• A failed install leaves a stale shim ahead of the verified runtime.
• Global install accidentally mutates the current repository or deletes project-local data on uninstall.
• Package publication occurs before native assets or checksums are available.
• Postinstall restrictions, proxies, or offline environments produce an opaque partial installation.
• The npm token/publisher path weakens release provenance.

Mitigation direction:

• Keep the GitHub release version and existing native asset/checksum contract authoritative.
• Generate or share the smallest platform manifest instead of maintaining duplicate mappings.
• Stage installation, validate the runtime, then switch the package-owned launcher atomically.
• Scope cleanup to package-owned paths and cover project-data preservation explicitly.
• Gate npm publication on the matching native asset matrix and integrity metadata.
• Return actionable unsupported/offline/proxy errors and document a direct-release fallback.
• Use npm trusted publishing/provenance and least-privilege release permissions.

When this issue is promoted from backlog, add an OpenSpec change and map each mitigation to its owning tasks before implementation.

[styler-ai]

Roadmap disposition: keep and pair in v0.5.2 with #456. The common release contract is faster correct local startup: exact native asset identity, checksums, platform mapping, atomic installation/materialization, offline and failure behavior, existing-atlas preservation, and packaged CLI/MCP proof.