@sunilaleti/hx 0.3.0-beta.1 → 1.0.0

package/CHANGELOG.md

@@ -28,6 +28,55 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [1.0.0] - 2026-10-31
+
+### Changed
+
+- The TypeScript build is the release: install it with `npm install --global @sunilaleti/hx`,
+  and run the same command again to update.
+- With nothing signed in, `hx` opens straight into the TUI, under the HX logo, and says to type
+  `/login`, instead of asking for an OpenRouter key in the shell before anything is on screen.
+  A model whose route is not signed in says to `/login` or pick another with `/model`, and the
+  first message after signing in goes through.
+
+### Removed
+
+- `hx upgrade`. Update by running the install command again.
+- The beta channel (`@sunilaleti/hx@next`). Every version is a stable release on `latest`.
+- The Python build. `hx-cli` on PyPI stops at 0.2.20 and gets no more releases. To move over,
+  run `uv tool uninstall hx-cli` and install from npm: `~/.hx` carries over as it is.
+  `install.sh` now checks for Node.js 22.15 or newer and installs from npm.
+- The `live` tests, which drove the Python build's internals against real APIs.
+
+### Security
+
+- A server in a project's `.hx/mcp.json` no longer starts by itself: a cloned repository could
+  run any command the moment `hx` opened in it. HX names each waiting server and what it runs;
+  `hx mcp approve <server>` starts it, and `hx mcp add` approves what it adds. An approval is for
+  that command, so a server whose command changes waits again. Existing project servers need
+  approving once.
+- Read, Grep, Glob, Symbols, Write and Edit ask before touching `~/.ssh`, `~/.aws`, `~/.gnupg`,
+  `~/.kube`, `~/.config/gh`, `~/.docker/config.json`, `~/.netrc`, `~/.npmrc`, `~/.pypirc` and
+  HX's `auth.json`, in every mode and through symlinks. The sandbox kept the shell out of them,
+  but these tools run outside it. An allow rule naming the file opens it.
+- A command hidden inside another no longer passes as read-only: `cat <(rm -rf src)`, `>(...)`,
+  zsh's `=(...)` and glob qualifiers, an `awk` program that pipes to or reads from a command,
+  `@include`, and `find -fprint0` all ask now.
+- A deny rule holds however the command is spelled: behind `NAME=value` assignments, by full
+  path, or behind a wrapper such as `nohup`, `timeout`, `sudo` or `xargs`. An allow rule no
+  longer covers a command with assignments it does not name.
+- `acceptEdits` covers only the project: a write outside it, through a symlink that leads out
+  of it, or into its `.git` or `.hx` folder asks.
+- `$HX_HOME` (`~/.hx`), which holds every transcript, is made private to its owner (`0700`).
+
+### Fixed
+
+- Reads that come before a write in one turn run concurrently, as reads elsewhere do.
+- A login shell that does not speak POSIX sh - csh, tcsh, fish - no longer makes every command
+  wait out its timeout: commands run in bash.
+
+---
+
 ## [0.3.0-beta.1] - 2026-10-31
 
 ### Changed
@@ -1054,7 +1103,8 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.3.0-beta.1...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/aletisunil/hx/compare/v0.3.0-beta.1...v1.0.0
 [0.3.0-beta.1]: https://github.com/aletisunil/hx/compare/v0.2.20...v0.3.0-beta.1
 [0.2.20]: https://github.com/aletisunil/hx/compare/v0.2.19...v0.2.20
 [0.2.19]: https://github.com/aletisunil/hx/compare/v0.2.18...v0.2.19

package/README.md

@@ -1,7 +1,8 @@
 # HX
 
-An agent harness for the terminal. Python core, its own terminal renderer,
-OpenRouter for models.
+An agent harness for the terminal. TypeScript on Node.js, its own terminal
+renderer, and models through OpenRouter or a ChatGPT, Claude or Devin
+subscription.
 
 HX runs in your project directory, reads and edits your code, runs commands in
 a sandboxed shell, and shows you what every turn costs.
@@ -11,12 +12,18 @@ a sandboxed shell, and shows you what every turn costs.
 ## Install
 
 ```sh
-npm install --global @sunilaleti/hx@next
+npm install --global @sunilaleti/hx
 ```
 
 HX runs on [Node.js](https://nodejs.org/) 22.15 or newer, on macOS and Linux.
-Update with `hx upgrade`. The `@next` tag is the beta channel while the
-TypeScript build is being tested; a beta upgrades to the next beta.
+Run the same command again to update. Then run `hx`: the first time, it opens
+with the HX logo and says to type `/login`.
+
+Or let the install script check your Node.js version and run that command:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/aletisunil/hx/main/install.sh | sh
+```
 
 ### `@sunilaleti/hx` on npm, `hx` in your terminal
 
@@ -37,9 +44,14 @@ to your `PATH`:
 export PATH="$(npm prefix --global)/bin:$PATH"
 ```
 
-The Python build, `hx-cli` on PyPI, keeps working on the same `~/.hx`:
-sessions, sign-ins and settings carry over in both directions. Install one or
-the other - both put a command named `hx` on your `PATH`.
+Coming from `hx-cli`, the Python build on PyPI? It is no longer released.
+Remove it, then install from npm - sessions, sign-ins and settings in `~/.hx`
+carry over:
+
+```sh
+uv tool uninstall hx-cli
+npm install --global @sunilaleti/hx
+```
 
 ### Credentials
 
@@ -329,6 +341,7 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp approve <server>     # let a server from the project's .hx/mcp.json start
 hx mcp login <server>       # sign in to a remote MCP server in the browser
 hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
@@ -336,7 +349,6 @@ hx auth login [provider]    # sign in (openrouter, openai-codex, devin, claude-c
 hx auth logout <provider>   # forget a stored credential
 hx docs [section]           # the manual; no argument lists its sections
 hx changelog [version]      # what shipped in each version
-hx upgrade                  # update to the latest release
 ```
 
 Print mode is the scriptable one: stdout carries only the assistant's text, so
@@ -373,7 +385,7 @@ allowlist it if you would rather not be asked:
 
 ### Keys
 
-Every key below is defined once, in `src/hx/keys.py`. `/help`, the hints line
+Every key below is defined once, in `src/keys.ts`. `/help`, the hints line
 under the prompt and this table all read from that registry, and any of them can
 be rebound (see [Keybindings](#keybindings)).
 
@@ -474,7 +486,7 @@ says so; copy the file over and drag or paste its path instead.
 #### Keybindings
 
 Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
-`src/hx/keys.py`:
+`src/keys.ts`:
 
 ```json
 {
@@ -721,7 +733,7 @@ route at another OpenAI-compatible endpoint - a gateway, or a recording proxy.
 stderr so stdout stays pipeable. `/prompt` shows the same thing inside a running
 session.
 
-The built-in prompt is `SYSTEM_PROMPT` in `src/hx/core/context.py`. It is
+The built-in prompt is `SYSTEM_PROMPT` in `src/core/context.ts`. It is
 replaced by the first of these that exists:
 
 | Source | Scope |
@@ -785,7 +797,7 @@ mapping semantic roles onto them. Drop one in `~/.hx/themes/mine.json` and
 ```
 
 The role names are pi's, so [pi](https://github.com/earendil-works/pi) theme
-files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
+files load here unchanged. `src/tui/themes/dark.json` is the reference.
 A few roles pi has no concept of may be left out, and borrow another role:
 `toolArgs`, the colour of a tool call's paths and patterns, borrows `accent`;
 `panel` and `mdCodeBlockBg` borrow `surface`; `userText` borrows `text`; and
@@ -842,7 +854,19 @@ Two independent layers guard every tool call, and both must pass.
 holds even in bypass mode. Shell commands are decomposed into their real
 segments first, so an allow rule for `git status` does not carry
 `&& rm -rf /` along with it; a command that cannot be decomposed with
-confidence prompts rather than passing.
+confidence prompts rather than passing. What runs inside a command counts as a
+segment of its own - `$(...)`, `<(...)`, `>(...)` - so `cat <(rm -rf src)` is
+not a read-only `cat`. A deny rule matches the command however it is spelled:
+`deny: Bash(rm:*)` also stops `FOO=1 rm`, `/bin/rm` and `nohup rm`. An allow
+rule covers only what it names, so `allow: Bash(ls)` does not cover
+`LD_PRELOAD=x ls`.
+
+**Credential files** - the same `~/.ssh`, `~/.aws` and `auth.json` the sandbox
+guards - always ask before Read, Grep, Glob, Symbols, Write or Edit touch them,
+in every mode, symlinks followed. Those tools run inside HX, outside the
+sandbox. An allow rule that names the file, such as `allow: Read(~/.ssh/config)`,
+opens that one file. A search that starts above them, from `$HOME`, leaves
+them out.
 
 **An OS sandbox** wraps command execution: Seatbelt on macOS, bubblewrap on
 Linux. The filesystem is readable, writes are confined to the project and the
@@ -855,7 +879,13 @@ and the Tavily and Devin keys) are removed from the environment of every
 command it runs.
 
 Modes cycle with shift+tab: `plan` (read-only — mutating tools are not even
-offered to the model), `default`, `acceptEdits`, `bypass`.
+offered to the model), `default`, `acceptEdits`, `bypass`. `acceptEdits` covers
+the project's own files: a Write or Edit outside the project, through a symlink
+that leads out of it, or into its `.git` or `.hx` folder still asks.
+
+**Nothing that arrives with a clone runs by itself.** Hooks in a project's
+shared `.hx/settings.json` are ignored, and a server in its `.hx/mcp.json`
+starts only once you approve it - see [Extending it](#extending-it).
 
 ---
 
@@ -1083,7 +1113,16 @@ construction.
 ```
 
 Or `hx mcp add local python server.py`, or
-`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
+`hx mcp add remote --url https://example.com/mcp`.
+
+A server in the project's `.hx/mcp.json` runs a command on your machine, and
+the file arrives with a clone - so HX does not start it until you approve it.
+A session names each one waiting, with what it runs. `hx mcp approve local`
+starts it from the next session on, and `hx mcp add` approves what it adds.
+The approval is for that command: if a `git pull` changes it, the server waits
+again. Servers in your own `~/.hx/mcp.json` need no approval.
+
+Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
 dropped rather than taking the session with it. A server that changes its tool
@@ -1186,23 +1225,26 @@ bypassed by delegating through `Task`.
 
 ```sh
 git clone https://github.com/aletisunil/hx && cd hx
-uv sync --extra dev
+npm ci
 
-uv run pytest                # the suite; live tests are deselected
-uv run ruff check . && uv run ruff format --check .
-uv run mypy                  # strict
-uv run hx                    # run from the checkout
+npm run check                # tsc, biome, and the source-literal check
+npm run build                # dist/hx.js, the bundle npm ships
+node dist/hx.js              # run from the checkout
+npm run e2e                  # build, then the whole end-to-end suite
+uv run ruff check . && uv run ruff format --check .   # the suite's own Python
 ```
 
-The suite is end-to-end. Each test in `tests/e2e/` starts the installed `hx`
-binary - on a real pseudo-terminal for the TUI, or as a plain subprocess for
+The suite is end-to-end, written in Python with pytest, and run with
+[uv](https://docs.astral.sh/uv/). Each test in `tests/e2e/` starts the `hx`
+bundle - on a real pseudo-terminal for the TUI, or as a plain subprocess for
 print mode and the other commands - in a private `$HOME` and `$HX_HOME`, and
 points it at a local OpenRouter stand-in with `HX_OPENROUTER_BASE_URL`, and
 at a ChatGPT stand-in with `HX_CODEX_BASE_URL`.
 Everything between the keyboard and the socket is the shipped code; only the
 model's replies are scripted. The screen is read back through a VT emulator,
 so assertions are on the cells a terminal shows, not on the bytes HX meant to
-write.
+write. The suite never imports HX: it tests `dist/hx.js` by default, and any
+other `hx` - an installed one, say - named by `HX_E2E_BIN`.
 
 Every run writes `e2e-report/`: `index.html` shows each test's outcome and
 every screen it checked, rendered in colour, and one text file per screen lets
@@ -1212,41 +1254,26 @@ two runs be compared with `diff -r`. CI uploads it from every test job as an
 Tests that need the OS sandbox are skipped where there is no backend
 (`sandbox-exec` on macOS, `bwrap` on Linux).
 
-Tests marked `live` hit a real API. The OpenRouter ones cost money:
-
-```sh
-OPENROUTER_API_KEY=... uv run pytest -m live tests/test_live.py
-
-# the Codex route draws on your ChatGPT subscription instead
-hx auth login openai-codex
-uv run pytest -m live tests/test_live_codex.py
-
-# and the Devin route on your Devin subscription
-hx auth login devin
-uv run pytest -m live tests/test_live_devin.py
-```
-
-They are the only place the wire formats, streaming, tool use and a genuine
-cache hit are proven against a real service; everything else runs against the
-stand-in.
-
 ### Layout
 
 ```
-src/hx/
-  cli.py config.py paths.py frontmatter.py git.py
+src/
+  cli.ts runtime.ts config.ts paths.ts frontmatter.ts git.ts trace.ts
   core/         loop, context assembly, compaction, late injection, sessions, usage
   auth/         credential store, OAuth flows, per-route resolution
-  providers/    OpenRouter, Codex, Devin, the model catalogue
+  providers/    OpenRouter, Codex, Claude Code, Devin, the model catalogue
   tools/        Bash, Read, Write, Edit, Glob, Grep, Symbols, TodoWrite, Task,
                 WebSearch, WebFetch, line anchors, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
   hooks/        the four events, the trust boundary, subprocess execution
-  skills/ agents/ mcp/
-  keys.py       keybinding registry: ids, defaults, descriptions, user overrides
+  skills/ agents/
+  mcp/          client, OAuth, and approval for a project's servers
+  keys.ts       keybinding registry: ids, defaults, descriptions, user overrides
   term/         the renderer: raw mode, input decoding, the differ, the screen
   tui/          views, commands, per-tool renderers, themes
     themes/     the shipped palettes, as JSON
+  py.ts pathlib.ts json.ts   Python's string, path and JSON behaviour, which
+                             HX's output and files were written against
 ```
 
 The core is headless and emits events; the TUI and print mode are both just
@@ -1257,44 +1284,43 @@ imports `tui/`.
 
 ## Releasing
 
-For maintainers. HX publishes to PyPI as **`hx-cli`** from CI, on a tag.
-
-One-time setup:
-
-1. Push the repo to `github.com/<owner>/hx` and update the URLs in
-   `pyproject.toml`.
-2. Create a GitHub environment named `pypi`.
-3. On PyPI, add a [trusted publisher](https://docs.pypi.org/trusted-publishers/)
-   for the project: owner, repo `hx`, workflow `ci.yml`, environment `pypi`.
-   No API token is stored anywhere.
+For maintainers. HX is published to npm as **`@sunilaleti/hx`**, on the
+`latest` tag, by CI. Every version is a stable release; there is no beta
+channel.
 
-Each release:
+A push to `main` whose `package.json` version is not on npm yet is a release:
+once lint, the test suite and the install script pass, CI's `release` job
+publishes it to npm, tags it `vX.Y.Z` and makes the GitHub release, with the
+version's `CHANGELOG.md` section as its notes. A push that leaves the version
+alone publishes nothing.
 
 ```sh
 # 1. move CHANGELOG.md's [Unreleased] entries under the new version, dated,
 #    and leave a fresh empty [Unreleased] behind
-# 2. bump __version__ in src/hx/__init__.py
-# 3. uv run pytest tests/e2e/test_cli.py  # the version must have a section
-git commit -am "release: X.Y.Z"
-git tag v$(uv run hx --version | cut -d' ' -f2) && git push origin main --tags
+# 2. bump "version" in package.json
+npm version X.Y.Z --no-git-tag-version
+# 3. the whole suite; the version must have a CHANGELOG section
+npm run e2e
+git commit -am "chore(release): X.Y.Z"
+git push origin main
 ```
 
 Step 1 is not optional and is not a convention: `tests/e2e/test_cli.py` fails the
-whole suite when `__version__` has no `CHANGELOG.md` section, so a release that
-skips it cannot get past CI to the `publish` job. The file ships inside the
-wheel and `hx changelog` prints it, so a version with no section there reaches
-users as a blank release.
+whole suite when the version has no `CHANGELOG.md` section, and the `release`
+job checks again before it publishes. The file ships inside the bundle and
+`hx changelog` prints it, so a version with no section there would reach users
+as a blank release.
 
-The `publish` job runs only on `refs/tags/v*` and only after lint, the test
-suite and an install-script run in a clean Debian container have passed. It builds with
-`uv build`, checks that the wheel's version matches the tag and has a `CHANGELOG.md`
-section, uploads via OIDC, and then creates the GitHub release with that section
-as its notes.
+One-time setup: CI publishes with npm's
+[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm
+token is stored anywhere. On npmjs.com, open `@sunilaleti/hx` → Settings →
+Trusted Publisher, choose GitHub Actions, and enter owner `aletisunil`,
+repository `hx` and workflow `ci.yml`, with no environment.
 
-To check a build before tagging:
+To see what npm would ship before releasing:
 
 ```sh
-uv build && ls dist/
+npm pack --dry-run
 ```
 
 ---
@@ -1306,13 +1332,11 @@ streaming with prefix caching and accurate cost accounting, session persistence
 and resume, the tool suite, the permission engine and OS sandbox, late
 injection, compaction, output capping, skills, subagents, MCP, and the TUI.
 
-Three routes to a model: an OpenRouter API key, a ChatGPT Plus/Pro
-subscription over OAuth, or a Devin subscription over OAuth. The model id
-decides which.
+Four routes to a model: an OpenRouter API key, a ChatGPT Plus/Pro
+subscription over OAuth, a Claude Pro/Max subscription through Claude Code, or
+a Devin subscription over OAuth. The model id decides which.
 
-Published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/), released
-from CI on a tag.
+Published to npm as [`@sunilaleti/hx`](https://www.npmjs.com/package/@sunilaleti/hx).
+The Python build that came before it, `hx-cli` on PyPI, stopped at 0.2.20.
 
-The one thing still unproven in CI is a live call on any route: the `live`
-tests exist and cover all three wire formats, tool use, reasoning replay and a
-genuine cache hit, but they need a credential and are deselected by default.
+No test reaches a real model: every route is proven against a local stand-in.