Skip to content

cli: Resolve nshm with versions, a lock and a shared installation - #2733

Open
huacnlee wants to merge 4 commits into
mainfrom
agent/nsh-add-outside-app
Open

huacnlee wants to merge 4 commits into
mainfrom
agent/nsh-add-outside-app

Conversation

@huacnlee

@huacnlee huacnlee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

nshm become NSH's dependency system, modelled on Cargo: the app declares them by package name, NSH resolves one version of each package across the app and its nshm, pins the result in nsh.lock, and installs every version once per machine for all apps to share. An nshm can now also be pure TSX (published as a Git repository with version tags) or provide a platform.

Changes

  1. Declaration. nsh.json "dependencies", keyed by package name, as Cargo.toml does:
{
  "dependencies": {
    "nsh-omarchy": "^0.3",
    "acme-ui": { "github": "acme/ui", "version": "^1.4" },
    "nsh-extra": { "version": "^0.6", "features": ["camera"] },
    "my-gauge": { "path": "../my-gauge" }
  }
}
  1. Resolution and lock. Versions come from the crates.io sparse index and from Git semver tags (v1.4.0 / 1.4.0; tag / rev pin one instead). The resolver walks the app's dependencies and each chosen nshm's own, one version per package, trying the locked version first, then the others newest first, and backtracks out of conflicts; when nothing fits, the error names each requirer. The app's entry decides where a package comes from. nsh.lock (format 2) records version, source, commit, checksum, installed dir, module, TSX exports, platform and dependencies. While the lock still fits, commands do not touch the network.
  2. Shared installation. ~/.nsh/nshms/ (NSH_HOME moves ~/.nsh): nsh-omarchy/0.3.2/, github.com/acme/ui/1.4.0/, github.com/acme/ui/<commit12>/, one bare clone per repository under .git/. .crate downloads are checked against the index's sha256; installs are atomic (written beside, then renamed).
  3. Two kinds of nshm. A Rust nshm (a crate with #[native_module]) links as before, now from the installed copy through [patch]. A TSX nshm is described by its nsh.json (name, version, nsh, exports, dependencies); the bundler aliases each locked export to its file, so it compiles into the app's bundle: a TSX app using only TSX nshm needs no Rust and ships them over the air. nsh check gets .nsh/types/<specifier>.d.ts re-exporting the source. A Rust nshm may export TSX too.
  4. Platform nshm. "platform": "<name>" plus a nsh-platform-<name> binary: --target <name> builds it in the app's .nsh/platforms/<name> and runs it as an external target, before looking on PATH.
  5. Commands. nsh add learns github:owner/repo@<req> and TSX nshm, prints what to import and when Rust becomes necessary, and restores the app's files on failure. New nsh remove and nsh upgrade (upgrade, since nsh update is the released self-update). nsh add also finds the app above the current directory and prints Cargo-style status lines.

The pre-release "modules" / "extensions" keys and lock format 1 were never released; the keys are rejected with a message, an old lock is resolved again.

Public API

  • nsh.json "dependencies": { "<package>": "<req>" | { "github" | "git" | "path", "version"?, "tag"?, "rev"?, "features"? } }: the app's nshm.
  • nshm nsh.json: "name", "version", "nsh" (requirement on NSH), "exports": { "<specifier>": "<file.tsx>" }, "dependencies", "platform".
  • nsh.lock format 2.
  • nsh add [<crate>[@req] | github:<owner>/<repo>[@req] | <git url>] [--path <dir>] [--tag <tag>] [--rev <rev>] [--features <f>...].
  • nsh remove <name>...: remove nshm from the app.
  • nsh upgrade [<name>...]: re-resolve to the newest versions the requirements accept.
  • NSH_HOME: moves ~/.nsh (where nshm are installed).
  • nsh_bundler::nshm::{LOCK, home, installed_dir, exports}: the bundler reads TSX exports from the lock.

Tests

  • cargo test -p nsh-cli -p nsh-bundler: all pass (317 + 99), including resolver tests (newest fitting version, lock kept while it fits, backtracking, app-chosen origin) and an end-to-end Git test: add by URL → lock → upgrade to a new tag → remove.
  • cargo clippy -p nsh-cli -p nsh-bundler --all-targets, cargo +nightly fmt --all: clean.
  • Manual on macOS with the built nsh:
    • TSX nshm in a local Git repo: nsh add file://… wrote "version": "^0.1.0" and the lock; an app importing Badge from it passed nsh build, nsh test (the badge renders) and nsh check.
    • Rust nshm from crates.io: nsh add nsh-omarchy downloaded and verified the .crate into ~/.nsh/nshms/nsh-omarchy/0.1.0, and nsh test built it into the headless runner, 2/2 passed.
  • tests/cli runtime::gpui_uses_its_workspaces_cargo_output_instead_of_a_stale_cli_sibling fails locally on main too (unrelated).
  • Not run: a platform nshm end to end (no real one exists yet), Windows paths, the full cargo test --workspace.

Docs

website/docs/nshm.md, cli.md (nsh add, nsh upgrade, nsh remove, external targets), project-structure.md, their zh-CN versions, and docs/dev/tooling.md.

🤖 Generated with Claude Code

@huacnlee huacnlee changed the title cli: Find the app above the current directory in nsh add cli: Find the app above the current directory and print status in nsh add Nov 21, 2026
nsh add writes { "<package>": "^<resolved>" } for crates.io and an
object with github/git/path for other sources, as Cargo.toml does. An
older "modules" list still builds and is rewritten on the next nsh add,
keeping each requirement and the pins in nsh.lock.

Agent: lead
@huacnlee huacnlee changed the title cli: Find the app above the current directory and print status in nsh add cli: Fix nsh add outside the app dir, print fetch status, list nshm as dependencies Nov 21, 2026
nshm are listed in nsh.json "dependencies" by package name and resolved
like crates: one version of each package across the app and its nshm,
the newest every requirement accepts, pinned in nsh.lock (format 2).
Versions come from the crates.io sparse index and from Git semver tags;
each is installed once per machine in ~/.nsh/nshms and shared by every
app.

An nshm is a Rust crate with a #[native_module], TSX described by an
nsh.json "exports" in a Git repository, or both. TSX nshm compile into
the app's bundle through bundler aliases read from the lock, so a TSX
app using only TSX nshm needs no Rust and ships them over the air. An
nshm with "platform" provides an external target, built from a copy in
the app's .nsh/platforms and tried before PATH.

nsh add learns github:owner/repo@req and TSX nshm; nsh remove and
nsh upgrade join it (upgrade, since nsh update is the self-update).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@huacnlee huacnlee changed the title cli: Fix nsh add outside the app dir, print fetch status, list nshm as dependencies cli: Resolve nshm with versions, a lock and a shared installation Nov 21, 2026

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.

1 participant