Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -195,3 +195,114 @@ jobs:
--generate-notes \
artifacts/*
fi

# -- registries -------------------------------------------------------------
#
# Both jobs authenticate by trusted publishing: the runner proves who it is
# with a short-lived OIDC token and the registry hands back a credential that
# expires with the run. There is no long-lived secret in either, which is why
# `id-token: write` appears and `secrets` does not.
#
# Each registry has to be told to trust this workflow, and *neither* can be
# configured for a package that does not exist yet. The first publish of any
# new package is therefore a manual one from a laptop; every release after it
# goes through here.

crate:
name: publish to crates.io
needs: build
if: github.ref_type == 'tag'
runs-on: ubuntu-latest
environment: Packaging
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4

# A crates.io version can never be republished, not even after a yank, so
# a tag that disagrees with Cargo.toml must stop the release here rather
# than burn the version number it would have gone out under.
- name: The tag and Cargo.toml must agree
run: |
WANT="${GITHUB_REF_NAME#v}"
HAVE="$(grep -m1 '^version = ' Cargo.toml | cut -d'"' -f2)"
if [ "$WANT" != "$HAVE" ]; then
echo "tag says $WANT, Cargo.toml says $HAVE"
exit 1
fi
shell: bash

- name: Install toolchain
run: |
rustup toolchain install stable --profile minimal --no-self-update
rustup default stable
shell: bash

# Re-tagging is a normal thing to do while a project is young, and the
# release job above is built for it. `cargo publish` is not: it fails
# outright on a version the registry already has, which would redden a
# rerun whose only crime is that it already succeeded.
- name: Has crates.io got this version already?
id: need
run: |
WANT="${GITHUB_REF_NAME#v}"
CODE="$(curl -sS -o /dev/null -w '%{http_code}' \
-A "tread-release" "https://crates.io/api/v1/crates/tread/$WANT")"
if [ "$CODE" = "200" ]; then
echo "tread $WANT is already on crates.io; nothing to publish"
echo "publish=no" >> "$GITHUB_OUTPUT"
else
echo "publish=yes" >> "$GITHUB_OUTPUT"
fi
shell: bash

- uses: rust-lang/crates-io-auth-action@v1
id: auth
if: steps.need.outputs.publish == 'yes'

- run: cargo publish --locked
if: steps.need.outputs.publish == 'yes'
env:
CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}

npm:
name: publish to npm
# Not `needs: build`. The launcher this publishes downloads its binary from
# the GitHub release at first run, so publishing it before the release
# exists would ship a package that cannot work until the next job finishes.
needs: publish
if: github.ref_type == 'tag'
runs-on: ubuntu-latest
environment: Packaging
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: 22
registry-url: https://registry.npmjs.org

# Trusted publishing needs a newer npm than the runner image ships.
- run: npm install -g npm@latest && npm --version

# The published version is the tag, always. package.json carries 0.0.0 in
# the repository so there is no second place to forget to bump.
- name: Stamp the version from the tag
working-directory: npm
run: npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version --allow-same-version

# Same reasoning as the crate job: a rerun of a tag that already shipped
# must be a no-op, not a red run.
- name: Publish
working-directory: npm
run: |
WANT="${GITHUB_REF_NAME#v}"
if npm view "@viict/tread@$WANT" version > /dev/null 2>&1; then
echo "@viict/tread $WANT is already on npm; nothing to publish"
exit 0
fi
npm publish --access public --provenance
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ corpus of linked documents. Crate `tread`, binary `tread`.
| `src/pager/` | viewport, scrolling, collapse tree, search |
| `src/nav/` | document stack, index parsing, link resolution; `external.rs` is the *policy*: the scheme allowlist (`http`, `https`, `mailto`), the refusal that names the offending scheme, and `vetted()` — the one constructor in the crate of the `sys::browser::Vetted` token that `open` requires |
| `src/select/` | visual selection, yank text |
| `npm/` | the npm package (SPEC.md §"Installing from a package manager"): `package.json`, one launcher and `lib/unpack.js`, no binary and no dependencies. It resolves the platform, fetches on first run **the same `.tar.gz` or `.zip` the releases page already publishes** — the release is never asked to carry a second, npm-shaped copy of every binary — verifies it against `SHA256SUMS` and only then reads the binary out of it, which is what `unpack.js` is for: node has `zlib` and no archive reader, so a tar walk and a zip central-directory walk cost a hundred lines where a dependency would cost the package its one rule, and hands the terminal over with stdio inherited so raw mode and drag-select reach the real program. `TREAD_BINARY` skips the lot. The version in `package.json` is `0.0.0` in the repository and stamped from the tag by `release.yml`, so there is no second place to bump — which also means the launcher only works from a published package, never from a checkout. Its data-directory table mirrors `src/plat/dirs.rs`; change one and change the other |

Keep platform FFI inside a backend under `src/sys/`; everything above `sys` is
platform-agnostic, and every `cfg(target_os)`-shaped *convention* (path syntax,
Expand Down
1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ license = "MIT OR Apache-2.0"
readme = "README.md"
keywords = ["pager", "markdown", "csv", "json", "code"]
categories = ["command-line-utilities", "text-processing"]
exclude = ["trajectory.json", "tools/__pycache__", ".claude", "CLAUDE.md", ".github"]

[[bin]]
name = "tread"
Expand Down
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,19 @@ $env:INSTALL_PATH = 'C:\tools'; irm https://raw.githubusercontent.com/viict/trea
$env:VERSION = 'v0.1.0'; irm https://raw.githubusercontent.com/viict/tread/master/install.ps1 | iex
```

From a package manager, if you already have one:

```sh
cargo install tread # crates.io; builds from source
npx @viict/tread README.md # npm; fetches the build for your machine once
```

The unscoped `tread` on npm is an unrelated package, so the scope is not
optional. `npm install -g @viict/tread` puts the binary on your `PATH` under its
own name. Set `TREAD_BINARY` to a `tread` you already have and the npm launcher
downloads nothing at all — which is what one global install shared by several
accounts, or a CI runner with no route out, wants.

Prefer not to pipe the internet into a shell? Read
[`install.sh`](install.sh) or [`install.ps1`](install.ps1) first, or take a
`.tar.gz` — a `.zip` on Windows — from the
Expand Down
63 changes: 63 additions & 0 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -639,6 +639,69 @@ does not match, and install to a per-user location on `PATH`
(`%LOCALAPPDATA%\Programs\tread` by default, `$env:INSTALL_PATH` to change it).
It reports how to add the directory to `PATH` when it is not already there.

## Installing from a package manager

Two registries carry `tread`, and neither changes what the program is: the
binary they deliver is the same static build the releases page holds, and
nothing installed from a registry ever reaches the network again.

```sh
cargo install tread # crates.io, built from source
npx @viict/tread README.md # npm
npm install -g @viict/tread
```

The npm scope is not optional: the unscoped `tread` on npm is an unrelated
package that has been there since 2016, and `npx tread` fetches *that*. The
README says so above the fold, because it is the one mistake a new user makes
without any way to tell they have made it.

**The npm package is a launcher, not a copy of the program.** It carries no
binary. On first run it fetches, from that version's GitHub release, the very
`.tar.gz` or `.zip` a person would download by hand and `install.sh` already
verifies — the release publishes one shape of each binary, not a second one cut
for npm — checks it against the release's `SHA256SUMS`, and only then reads the
binary out of it and puts it where it can be executed. An archive whose checksum
does not match is never opened; the run fails, saying so. Nothing unverified is
ever run, and nothing is left behind for a later run to pick up.

Reading the archives is the launcher's own work, because node has `zlib` built
in and no archive reader: a tar is 512-byte headers each followed by its file,
and a zip is a central directory of deflate streams. Walking both costs about a
hundred lines and keeps the package's dependency count where the rest of the
project keeps it.

The choice not to download at *install* time is deliberate. A `postinstall`
script is dead weight under `npm ci --ignore-scripts` and under pnpm's default
script blocking — the package would install and the binary would silently never
arrive. Fetching at first run costs a moment once and works everywhere.

The binary is state, not cache, so it lives under the platform's data directory
rather than its cache directory: a cache is something the OS is entitled to
delete, and a `tread` that evaporates leaves an offline machine unable to read
anything. An explicitly set `XDG_DATA_HOME` wins on every platform, including
macOS, by the same reasoning `src/plat/dirs.rs` gives for caches.

| Platform | Location |
| --- | --- |
| Linux | `$XDG_DATA_HOME/tread/<version>/`, else `~/.local/share/tread/<version>/` |
| macOS | `~/Library/Application Support/tread/<version>/` |
| Windows | `%LOCALAPPDATA%\tread\<version>\` |

A version is a directory, so upgrading needs no invalidation rule: a new version
writes a new directory, and the others are removed once the new binary has run.

`TREAD_BINARY` points at a `tread` that already exists and skips all of it —
what one global install shared by several accounts wants, and what a runner with
no route out of the network needs. It is honoured exactly: if it names something
that is not there, the run fails rather than quietly downloading a second copy.

What this costs, stated plainly: `npm ci` no longer reproduces the whole tool
from the lockfile. The lockfile pins the launcher; the binary is fetched
afterwards and vouched for by its checksum instead. Anyone who needs the
stronger guarantee should install from crates.io, from `install.sh`, or from the
releases page — all three deliver the program itself.

## Directories

A directory is something to read, not an error. `tread some/dir` lists it, and a
Expand Down
60 changes: 60 additions & 0 deletions npm/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# tread

A terminal reader for markdown, CSV, JSON and source code — `less`, but it
understands what it is showing: collapsible headings, real tables, colored
links, and navigation across a corpus of linked documents.

```sh
npx @viict/tread README.md
```

Or install it so the binary is on your `PATH` as `tread`:

```sh
npm install -g @viict/tread
```

## What this package is

`tread` is a Rust program with no dependencies. This package is a small launcher
that downloads the build for your machine on first run, verifies its SHA-256
against the checksums published with the release, and then gets out of the way.
Nothing is downloaded at install time, so `npm ci --ignore-scripts` and pnpm's
default script blocking are not a problem.

The binary is kept per version under your platform's data directory:

| Platform | Location |
| --- | --- |
| Linux | `$XDG_DATA_HOME/tread/<version>/`, else `~/.local/share/tread/<version>/` |
| macOS | `~/Library/Application Support/tread/<version>/` |
| Windows | `%LOCALAPPDATA%\tread\<version>\` |

Older versions are removed once a new one has been fetched.

## Using a binary you already have

Set `TREAD_BINARY` and nothing is ever downloaded:

```sh
export TREAD_BINARY=/usr/local/bin/tread
```

That is the right answer for a machine with several user accounts sharing one
install, and for a CI runner with no route to the internet. If `TREAD_BINARY`
names something that is not there, the run fails — it never falls back to
downloading a second copy behind your back.

## Other ways to install

```sh
cargo install tread # from crates.io, builds from source
```

Prebuilt archives for every supported platform, and the `SHA256SUMS` this
launcher verifies against, are on the
[releases page](https://github.com/viict/tread/releases).

## Licence

MIT OR Apache-2.0.
Loading
Loading