Skip to content

cli: Run the nsh CLI the project pins - #2736

Open
YougLin-dev wants to merge 2 commits into
longbridge:mainfrom
YougLin-dev:cli/toolchain-pin-v2
Open

YougLin-dev wants to merge 2 commits into
longbridge:mainfrom
YougLin-dev:cli/toolchain-pin-v2

Conversation

@YougLin-dev

Copy link
Copy Markdown
Contributor

Refs #2712

This is the in-nsh version of the toolchain pin. No second binary, no second command. Users always run nsh.

Description

A project can pin the nsh CLI it builds with, so every nsh call into that project (including from outside an app directory) uses the pinned version:

"toolchain": {
  "nsh": { "version": "0.6.1" }
}

or pin an exact Git revision:

"toolchain": {
  "nsh": { "rev": "<40-hex>", "repository": "YougLin-dev/nsh" }
}

On every invocation, before any subcommand runs, the running nsh:

  1. Reads the nearest nsh.json and parses toolchain.nsh.
  2. If the selection matches this build (by release version, or by NSH_GIT_SHA_FULL for a rev pin), proceeds in place — no extra process.
  3. Otherwise installs the pinned CLI into $NSH_CACHE/toolchains/<owner>__<repo>/<tag-or-rev>/:
    • Release pin: downloads nsh-<host>.{tar.gz,zip} from the repository's GitHub releases, verifies .sha256, unpacks.
    • Rev pin: builds the CLI from the Cargo git checkout at that revision (cargo build --release -p nsh-cli); the build target lives under the cache so cache cleans trigger a re-build.
  4. execs the pinned CLI with the original arguments, replacing this process.

A project without a pin, or with a pin that matches the current build, runs in place. The pin check happens before any subcommand handler, so it catches nsh run, nsh add, nsh test, --target dispatch, etc. — there is no other entry point. No new command or binary name: the tool is nsh, period.

Public API

  • nsh.json: "toolchain": { "nsh": { "version": "<release>", "rev": "<40-hex>", "repository": "<owner>/<repo>" } } — selects the CLI. Either version or rev is required. repository defaults to longbridge/nsh.
  • Environment: NSH_CACHE — cache root (defaults to the platform cache directory plus nsh).

How to Test

  • cargo test -p nsh-cli toolchain — 6 tests pass (pin parsing, validation, matching, tag prefix, cache root).
  • cargo clippy -p nsh-cli --all-targets -- -D warnings — clean.
  • cargo check -p nsh-cli — pass.
  • Real-release end to end (macOS arm64): in a directory with toolchain.nsh.version = "0.6.1", nsh --version first printed nsh 0.6.1 (2f51d86) after downloading and unpacking the published archive; a second run finished in 0.02s; without a pin in the directory, the running nsh used its own version (no exec).

No full cargo test --workspace run; only the CLI's resolver and the new toolchain module changed. No UI or platform behavior touched.

Checklist

  • I have read the CONTRIBUTING document and followed the guidelines.
  • Reviewed the changes in this PR and confirmed AI generated code (if any) is accurate.
  • Passed cargo test --workspace, cargo +nightly fmt --all and clippy (including the Catalyst and Android runs for platform code). — Ran the affected crate's tests and clippy; see How to Test.
  • Changes to what apps use keep what released versions shipped and come with a case in tests/compat/ (cargo xtask compat). — New nsh.json key; no app-facing API changed. Not applicable.
  • Ran the related examples/gallery demos on iOS and Android (if the change is visible or platform-specific). — Not visible; not applicable.

A project can pin the nsh CLI its toolchain expects in nsh.json, via
toolchain.nsh.version (a release, e.g. 0.6.1) or toolchain.nsh.rev (a
full Git commit). On every invocation, the running nsh reads the pin
before any subcommand runs. If the selection matches this build it
proceeds in place; otherwise the pinned CLI is looked up from the cache
($NSH_CACHE/toolchains/<owner>__<repo>/<tag-or-rev>/). On a cache miss,
a release pin downloads the prebuilt archive from the repository's
GitHub releases, verifies its SHA-256 and unpacks it; a Git-rev pin
builds the CLI from the Cargo checkout at that revision. Either way,
the running nsh replaces itself (exec) with the pinned CLI, forwarding
the original arguments.

No new command: the user runs `nsh`. Every nsh call site -- IDE tasks,
agents, --target dispatch, bare `nsh add` -- goes through the same
pin-aware entry.
@huacnlee

Copy link
Copy Markdown
Member

💡 Needs the maintainer's call: this adds a new public nsh.json key that makes every nsh call download (or build) and exec another CLI.

Reviewed head 40c69dc. cargo test -p nsh-cli toolchain: 6 pass. The code is tidy, but the design questions from #2712 are still open:

  • Public surface: new toolchain.nsh.{version,rev,repository} key and NSH_CACHE env var. Cargo/rustup precedent (rust-toolchain.toml) exists, but it is a project-wide policy choice for NSH.
  • Trust: crates/nsh-cli/src/toolchain.rs lets any nsh.json name an arbitrary repository; running any nsh command inside a cloned project then silently downloads and execs a binary from that fork (the checksum comes from the same release, so it proves integrity, not origin). There is no prompt and no opt-out env var. At minimum: restrict to longbridge/nsh by default, or ask before installing.
  • Rev pins depend on a Cargo git checkout already being present and run cargo build --release implicitly on first call.
  • Windows exec spawns a child and keeps the parent alive instead of replacing it.
  • Every invocation now walks up for nsh.json and parses it before any subcommand (small, but on the hot path of every command).

Suggest keeping this under the #2712 discussion until the maintainer decides whether NSH should pin its own CLI at all.

🤖 Noop (reviewer) · AI agent acting for @huacnlee

A cloned project could otherwise escalate any `nsh` invocation into
running code from an arbitrary fork. The SHA-256 we verify against the
release proves integrity, not origin.

`toolchain.nsh.repository` now defaults to longbridge/nsh and stays on
that trust root. Any other repository is refused unless the user
acknowledges it: set `NSH_TOOLCHAIN_ALLOW=owner/repo,...` for
non-interactive runs, or accept an interactive prompt on a TTY. The
gate fires before the install step, so a malicious project never
downloads code on the way to failing.
@YougLin-dev

Copy link
Copy Markdown
Contributor Author

Addressed the trust finding — that was a real bug, not a style choice. Pushed as 586d169.

  • toolchain.nsh.repository now defaults to longbridge/nsh, which is implicitly allowed. Any other repository is refused until the user acknowledges it via NSH_TOOLCHAIN_ALLOW=owner/repo,... on a non-interactive shell, or accepts an interactive prompt on a TTY. The gate fires before the install step, so a cloned project cannot cause code execution on the way to erroring out. cargo test -p nsh-cli toolchain: 8 pass (was 6); cargo clippy -p nsh-cli --all-targets -- -D warnings: clean.

The rest of the findings are noted:

  • Public surface: agreed that whether NSH should own a toolchain pin is a project-level decision; this PR does not pre-empt it.
  • Rev pins requiring a Cargo checkout: when the checkout is missing the install step fails with a clear error (no silent network). If you want it to fetch first, that is a one-line cargo metadata warm-up; say the word.
  • Windows re-exec: documented the surrogate — there is no exec on Windows, so the pinned CLI is spawned synchronously and the wrapper exits with its status. Ctrl+C / job-object signals propagate to the child.
  • Walk-up cost: one nsh.json read (or none) per invocation before any subcommand. If that lands on your hot path we can cache the negation for the process lifetime or memoize across runs.

Holding for the #2712 design decision.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants