@runfile/cli 1.1.6 → 1.7.1

package/README.md

@@ -23,7 +23,8 @@ web/runfiles/build.run → run web:build
 ```
 
 A target is a file, its name is its path, and its first comment block is its description. There is no central
-file to merge, so two people adding a task never conflict.
+file to merge, so two people adding a task never conflict. `run :list` shows the first line of each description
+— one line per target, cut to the terminal's width — and `run <target> --help` shows the whole block.
 
 ```sh
 # runfiles/dev.run
@@ -44,8 +45,23 @@ $ run :list
 
 ## Quick start
 
+Linux and macOS:
+
+```bash
+curl -fsSL https://git.joaoverona.com/joaaoverona/runfile/releases/download/latest/install.sh | sh
+```
+
+Windows, in PowerShell:
+
+```powershell
+irm https://git.joaoverona.com/joaaoverona/runfile/releases/download/latest/install.ps1 | iex
+```
+
+Either one installs a single binary: `~/.local/bin/run`, or `run.exe` under `%LOCALAPPDATA%\runfile\bin`, which
+the PowerShell script adds to your PATH for you — open a new shell and `run` is there. `RUNFILE_VERSION` installs
+a release other than the latest, and `RUNFILE_INSTALL_DIR` chooses where it goes.
+
 ```bash
-curl -fsSL https://github.com/JoaaoVerona/runfile/releases/latest/download/install.sh | sh
 run :init             # creates runfiles/ with an example
 run :list             # every target, with descriptions
 run <target> --help   # what one target does, and what it reads
@@ -136,27 +152,27 @@ $ docker exec -i db psql -U app < seed.sql
 
 ### Doing several things at once
 
-`.parallel` on a `for` fans out its iterations, and labels every line so you can tell them apart.
-
-It is block-scoped, so **where it sits is what it covers**: inside the loop it parallelises the iterations and
-nothing else, and at the top of the file it would cover every command in the target.
+`parallel for` runs every iteration at once and waits for the last. What is inside one iteration still runs in
+order, so each service is built before it is pushed, and every line carries the name of the iteration it came
+from.
 
 ```sh
-# runfiles/pull.run
-# Pull every service image
+# runfiles/release.run
+# Build and push every service image, then say so
 
-for compose in glob("**/docker-compose.yml")
-	.parallel
-	.ignore-errors
-
-	$ docker compose -f {{ compose }} pull
+parallel for svc in ["api", "web", "worker"]
+	$ docker build -t {{ svc }} services/{{ svc }}
+	$ docker push {{ svc }}
 end
+
+print("all three pushed")
 ```
 
 ```
-[docker] api      Pulling
-[docker] web      Pulling
-[docker] postgres Pull complete
+web | Successfully built 9a0c41e2b7d3
+api | Successfully built 1f2e86c0a4b5
+worker | The push refers to repository [docker.io/library/worker]
+all three pushed
 ```
 
 ### JSON without the backslashes
@@ -190,7 +206,7 @@ end
 run _aws -- s3api put-bucket-policy --bucket {{ bucket }} --policy {{ policy }}
 ```
 
-`run :format` lays the block out, and a missing brace is underlined in your editor as you type — not reported
+`run :lint` lays the block out, and a missing brace is underlined in your editor as you type — not reported
 by the far end an hour later.
 
 ### Reading JSON without jq
@@ -365,22 +381,28 @@ Line-oriented, with one rule: **the language is the default, the shell is marked
 
 | Line | Meaning |
 | --- | --- |
-| `# text` | A comment. The leading block is the target's description. |
+| `# text` | A comment, to the end of the line. It may follow code. The leading block is the target's description. |
 | `.name = value` | A property. |
 | `$ echo hi` | Hand this line to a shell. |
 | `exec python3` … `end` | Run a command with the block as its stdin. |
+| `detach $ npm run dev` | Start this one command and do not wait for it. Also `detach exec …`. |
 | `json` … `end` | A block of JSON, as one value. |
-| `let x = 1` | Bind a value. `x = 2` rebinds. `let a, b = pair` takes a list apart. |
+| `let x = 1` | Bind a value. `x = 2` rebinds. `let a, b = pair` takes a list apart. A name is bound before it is read. |
 | `if` / `else if` / `else` / `end` | Branch. However many `else if`s, one `end`. |
 | `for x in list` / `end` | Loop over a list. `for k, v in pairs` unpacks each item. |
+| `parallel do` / `parallel for x in list` … `end` | Run each statement inside, or each iteration, at once. |
 | `while c` / `until c` / `loop` / `end` | Loop on a condition, on its negation, or forever. |
 | `break` / `continue` | Leave the innermost loop, or start its next pass. |
 | `match` / `case` / `default` / `end` | Dispatch on a value. A label is a quoted string: `case "linux"`. |
 | `retry n [every s]` … `end` | Run the block again while it fails, up to `n` times. |
 | `do` … `end` | A block with no condition, so a property can cover a few commands. |
-| `run other-target` | Run another target, in this process. |
+| `run other-target` | Run another target, in this process, starting from this one's environment. |
 | `print(…)` | Anything else is an expression, evaluated for its effect. |
 
+A `#` opens a comment where it begins a word — the shell's own rule, so it reads the same on both sides of the
+marker, and `a#b` is one word in either half. The text after `$ ` is the shell's, `#` and all, and so is an
+`exec` block's body; everything else this language reads takes a comment at the end of the line.
+
 ### Values
 
 Strings, numbers, booleans and lists — **strict, with no coercion.** `"a" + 1` is an error telling you to use
@@ -390,7 +412,8 @@ Lists nest as deep as you like, which beats packing several fields into one stri
 
 ```sh
 for volume, owner in [
-	["prometheus-data", "65534:65534"],
+	["prometheus-data", "65534:65534"], # nobody
+	# the rest run as themselves
 	["kvrocks-data", "999:999"],
 ]
 	$ docker run --rm -v {{ volume }}:/v alpine chown -R {{ owner }} /v
@@ -448,6 +471,47 @@ end
 included. Under `--dry-run` a conditional loop walks its body once: a preview performs none of the effects the
 condition is waiting on, so how often is not a thing it can honestly answer.
 
+### Parallel blocks
+
+`parallel do` runs every statement directly inside it at once — a `$` line, a `run`, a call, a whole `if` or
+`for` — and waits for the last. `parallel for` does the same with every iteration. Inside a branch everything
+runs in order, as it does anywhere else: only what is marked `parallel` fans out, so nesting one fans out again.
+
+```sh
+# runfiles/check.run
+# Every check at once: tests, lint, and each subproject's own
+
+parallel do
+	$ cargo test
+	$ cargo clippy -- -D warnings
+
+	parallel for ns in RUN.namespaces
+		run {{ ns }}:check
+	end
+end
+```
+
+- Each branch works on **its own copy of the variables**. Nothing it binds reaches the other branches or the code
+  after the block, so assigning a name bound outside the branch is a parse error — that value would be lost. A
+  `let` directly inside `parallel do` binds nothing anyone can read, and is one too.
+- Every branch **runs to completion before a failure is reported**, so a set of services is never left half
+  started. `.ignore-errors` on the block forgives each branch.
+- Every line a branch prints carries its name, **in a colour of its own**: the target it runs, the iteration's
+  value, or as many words of its command as tell it from its siblings — `cargo test` and `cargo clippy`.
+  Siblings take consecutive colours, so the output you are reading side by side is the output guaranteed to
+  look different, and the names are padded to the widest of them so the `|` stands in one column:
+
+  ```
+  web-admin | ready on :3001
+  web-app   | ready on :3000
+  web-blog  | ready on :3002
+  ```
+
+  `NO_COLOR` turns the colour off, `FORCE_COLOR` turns it on through a pipe. A branch reads nothing from the
+  terminal, and `confirm()` refuses to ask inside one.
+- Branches run at once, so neither `break` nor `continue` can reach a loop outside the block, and `break` cannot
+  stop a `parallel for`, whose iterations are already running; `continue` ends one of them.
+
 ### Where values come from
 
 | Source | From |
@@ -490,7 +554,9 @@ Environment
 ```
 
 Nothing is declared for that — a `?` chain is what makes a value optional, and the literal it ends in is the
-default. `run --stdin-args deploy` asks for the same list, in the same order, **before anything runs**.
+default. `run --stdin-args deploy` asks for the same list, in the same order, **before anything runs**. A name
+the target sets for itself with `.env.NAME` — above the read, or in a `_shared.run` — is not on the list at all,
+since nothing the caller passes would reach it.
 
 That refusal has one exception, and it is the useful one: **a target that reads `ARGS`**. A wrapper can read
 any word, so it gets any word — a `--flag` it does not claim for itself joins the positionals where it was
@@ -622,28 +688,148 @@ skipped by `-y`, in CI, and under `--dry-run`, where there is nothing to approve
 A line that is only a value — `exit`, `abc`, `35` — is a parse error, since it computes something and throws
 it away. Most often it is a call with the parentheses left off, and the message says so.
 
+### Names are checked before anything runs
+
+A call to a function the language does not have, a read of a name nothing has bound, or a `RUN` key that does not
+exist stops the run **before its first line** — wherever it sits, a branch that would not have been taken included —
+and every one in the file is reported at once, with what you probably meant:
+
+```bash
+$ run backup
+[runfile] error: /home/you/shop/runfiles/backup.run: line 12: unknown function `exists`; did you mean `directory_exists` or `file_exists`?
+[runfile] error: /home/you/shop/runfiles/backup.run: line 15: `regoin` is not defined; did you mean `region`?
+```
+
+A name counts once any path to the line can have bound it: a `let` inside an `if` still binds for what follows
+its `end`, and a pass of a loop sees what an earlier pass bound. What does not reach past its block is a loop's
+own name and anything a `parallel` branch binds; a `_shared.run` binds with its top-level `let`s. A read behind
+a `?` is checked too, since a name nothing binds takes the fallback every time. And `x = 2` needs a `let x`
+above it — otherwise a typo in the name being updated would quietly start a new one.
+
+Your editor underlines the same names as you type them — it is the runner's own check, served by `run :lsp` —
+and `run :lint` reports them for every runfile in the project at once.
+
+### So is what fails every time
+
+Some lines fail whenever they run, whatever the run is given, and some never do what they say. Those stop the run
+before its first line too, with what to write instead:
+
+```bash
+$ run release
+[runfile] error: /home/you/app/runfiles/release.run: line 4: `+` needs numbers, and `ARG.build` is a string [wrong-type]; `number(ARG.build)` reads it as one
+[runfile] error: /home/you/app/runfiles/release.run: line 9: `RUN.os == "darwin"` is always false: `RUN.os` is only ever `linux`, `mac` or `windows` [never-equal]; write `"mac"`
+```
+
+Nothing is converted, and an argument or an environment variable is always a string — so `ARG.build + 1` fails every
+time, and so does `if ENV.CI`, since an `if` needs `true` or `false`. A call given one argument too many, a regex that
+does not compile, `xs[-1]`, `case "ok"` under `match $ make`, `if code_of($ make)`: each is reported wherever it sits.
+What a value can be is worked out only as far as the file is sure of it — `ENV.PORT ? 3000` is a string or a number, so
+nothing is said about `+` on it. [LANGUAGE-CHECK-RULES.md](LANGUAGE-CHECK-RULES.md) lists every rule, what it leaves
+alone, and why.
+
+### The shell is checked too
+
+The shell in a runfile is read before anything runs as well — every `$` line, every `exec` block for `sh` or
+`bash`, every capture — the way bash will read it, with each `{{ … }}` as the one quoted word it becomes. What
+bash would refuse, and what is wrong every time it runs, stops the run with what to write instead:
+
+```bash
+$ run emulate
+[runfile] error: /home/you/app/runfiles/emulate.run: line 4: `$HOME` in `"$HOME/Android/Sdk"` is kept as written, since a string is not shell -- and on line 9 this value is used as a path, which then starts with `$HOME` itself [unexpanded-string]; write `{{ ENV.HOME }}` in its place
+```
+
+A quote left open, a `fi` with no `if`, an interpolation wrapped in quotes of its own, a `*` the shell never
+expands, `cd` as the last command of its shell, `$1` in a shell that is given no arguments, `[ -f .env; then`,
+`sort names.txt > names.txt`, a `find -exec` with nothing to end it: each rule reports only what is wrong every
+time, and never a line that could be right — no style, no guesses. Your editor
+underlines the same findings and `run :lint` reports them; [SHELL-CHECK-RULES.md](SHELL-CHECK-RULES.md) lists
+every rule, what it leaves alone, and why.
+
 ## Properties
 
 Set at the top of the file, or inside a block where marked.
 
-| Property | Effect | In a block? |
-| --- | --- | :-: |
-| `.shell` | Which shell `$` lines use. | ✅ |
-| `.env.NAME` | Set an environment variable. | ✅ |
-| `.workdir` | Where commands run. | ✅ |
-| `.parallel` | Run this block's commands at once. On a `for`, its iterations. | ✅ |
-| `.ignore-errors` | Keep going when a command fails. | ✅ |
-| `.logging` | Announce each command on stderr before it runs. Off unless set. | ✅ |
-| `.env-file` | Load a `.env` file (encrypted values are decrypted in memory). Appends. | ✅ |
-| `.add-path` | Prepend a directory to `PATH`. Appends. | ✅ |
-| `.watch` | Re-run when matching files change. A `!` prefix excludes. | |
-| `.alias` | Another name for this target. | |
-| `.detach` | Start the commands and do not wait. | |
-| `.only-in-directories` | Machine-wide targets only: offer this one inside these directories. Appends. | |
+| Property | Effect | In a block? | Flag? |
+| --- | --- | :-: | :-: |
+| `.shell` | Which POSIX shell `$` lines use. | | |
+| `.env.NAME` | Set an environment variable. | ✅ | |
+| `.workdir` | Where commands run. | ✅ | |
+| `.ignore-errors` | Keep going when a command fails. | ✅ | ✅ |
+| `.logging` | Announce each command on stderr before it runs. Off unless set. | | ✅ |
+| `.env-file` | Load a `.env` file (encrypted values are decrypted in memory). Appends. | ✅ | |
+| `.add-path` | Prepend a directory to `PATH`. Appends. | ✅ | |
+| `.watch` | Re-run when matching files change. A `!` prefix excludes. | | |
+| `.only-in-directories` | Machine-wide targets only: offer this one inside these directories. Appends. | | |
+
+A **flag** is written bare for `= true`, or given a bool. A constant that can never be one is refused where it
+is written — `.ignore-errors = 23` and `.ignore-errors = "true"` are both errors, and the second says to drop
+the quotes. A value the run works out is left to the run: `.ignore-errors = ENV.CI` and
+`.ignore-errors = ARG.p ? ENV.CI ? "false"` are how a flag is decided from outside the file, and there `true`,
+`false`, `1` and `0` are all understood. Anything else stops the run rather than reading as `false`, because
+a flag that quietly did not take effect is found out much later.
+
+A property is applied **where it is written**: it can read a binding above it, and it takes effect from there
+down. The environment works the same way — a value reads it as it stands at its own line, so a property can be
+built from what a `.env-file` above it loaded, or from another `.env` above it:
+
+```sh
+# runfiles/build.run
+# Build into a directory the command line picks
+
+let out = concat("target-", ARG.profile ? "debug")
+
+.workdir = out
+
+$ ls
+```
+
+```sh
+# runfiles/migrate.run
+# Migrate the database the local .env points at
+
+.env-file = ".env"
+.env.DATABASE_URL = concat("postgres://", ENV.DB_HOST, "/app")
+
+$ sqlx migrate run
+```
+
+Four of them describe the whole file rather than the commands under them — `.shell`, `.logging`, `.watch` and
+`.only-in-directories` — and those have to be written above its first statement.
+
+`.shell` names one of the eight shells `$` knows how to drive: `sh`, `bash`, `dash`, `ash`, `zsh`, `ksh`,
+`busybox` or `brush`. Any other interpreter is named on the line instead, with `exec` — which is the same
+mechanism, and says so where it can be read:
+
+```sh
+# runfiles/list.run
+# List the current directory, whatever the platform
+
+if RUN.os == "windows"
+	exec pwsh
+		Get-ChildItem
+	end
+else
+	$ ls -la
+end
+```
+
+**The target's own `.env.NAME` wins over the caller's environment; a `.env-file` does not.** An assignment
+written in the file is the one way a target can force a value, so `PORT=4000 run serve` still serves on 3000
+under `.env.PORT = "3000"` — and `ENV.PORT` and a command's `$PORT` both say 3000. A file is a default, the
+dotenv convention: what the caller exported beats it. A default the caller *may* override is spelled out, and
+`--help` shows it as one:
+
+```sh
+# runfiles/serve.run
+# Serve locally
+
+.env.PORT = ENV.PORT ? "3000"
+
+$ node server.js
+```
 
 `.env-file` and `.add-path` **append**, so a block adds to what it inherited rather than replacing it, and a
-block's file can be named by something the body worked out — which a header property cannot do, because it
-resolves before any statement runs:
+block's file can be named by something that block worked out:
 
 ```sh
 # runfiles/deploy.run
@@ -670,6 +856,33 @@ runfiles/_aws.run       → run _aws     (a helper other targets call)
 runfiles/deploy.run     → run deploy
 ```
 
+**A target that `run`s another hands it its environment.** Whatever a command on that line would be given —
+the caller's `.env`, `.env-file` and `.add-path`, a block's as well as the header's, and what the caller was run
+with itself — is where the target it runs starts. That target layers its own settings over it the way it would
+over your shell: its own `.env` wins, and its own `.add-path` goes in front. So a helper needs no environment of
+its own:
+
+```sh
+# runfiles/_aws.run
+# The AWS CLI, with whatever credentials the calling target loaded
+
+$ docker run --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY amazon/aws-cli {{ ARGS }}
+```
+
+```sh
+# runfiles/backups.run
+# List the production backups
+
+.env-file = ".env.production"
+
+run _aws s3 ls s3://example-backups
+```
+
+A value that only a `.env-file` supplied is still a default when it arrives, so the target's own `.env-file`
+replaces it: a `ci` target that loads `.env` and runs `test` does not push the development database over
+`test`'s own `.env.test`. `$ run test` is different. A new process can only be handed variables, so there the
+caller's `.env-file` values arrive as if you had exported them, and they beat `test`'s own file.
+
 `do … end` is a block with no condition — somewhere for a property to go when it should cover a few commands
 and not the whole target:
 
@@ -738,6 +951,10 @@ excluded it. Relative entries are relative to your home. It is the one property
 set: their targets are visible to anyone reading the repository, so hiding some by working directory would
 bring back the very invisibility this exists to fix.
 
+A scope decides where a target is offered, not what gets checked. `run :lint` inside the machine-wide directory
+checks every file in it, scoped or not — and so does `run :lint --include-global` from anywhere else, since a
+project's lint leaves the directory out otherwise.
+
 **Not in CI.** A runner's home directory is nobody's, so `run` reads none of the three there: what runs is
 what is checked in and reviewable. This is also why nothing has to be cleaned up after a job.
 
@@ -770,11 +987,11 @@ whose state is still worth keeping, so a `setup` run under it is still recorded.
 | `run <target> [args…]` | Run a target |
 | `run :list` | List every target (`--names`, `--json` for tooling) |
 | `run :init` | Create `runfiles/` with an example |
-| `run :format [path…]` | Format runfiles in place (`--check`, `--stdout`) |
+| `run :lint [path…]` | Format runfiles in place and report anything the runner would refuse (`--check` writes nothing, `--stdout`) |
 | `run :env <sub>` | Manage `.env` files: `init`, `get`, `set`, `encrypt`, `decrypt`, `rotate`, `inject`, `secret-keys` |
 | `run :completions <command> <shell>` | `install`, `uninstall` or `output` a completion script for `bash`, `zsh`, `fish` or `powershell` |
 | `run :generate <editor>` | Task files for `zed`, `jetbrains` or `vscode`, merged into what is there |
-| `run :update` | Update the binary |
+| `run :update [version]` | Update the binary to the newest release, or to the tag named; `--channel=github` takes it from the GitHub mirror, `--force` reinstalls |
 
 | Flag | |
 | --- | --- |
@@ -787,11 +1004,29 @@ whose state is still worth keeping, so a `setup` run under it is still recorded.
 
 Flags belong **before** the target name; everything after it is passed to the target.
 
-`run :format` has no settings: one shape, everywhere. It reindents with tabs, spaces expressions, places blank
+`run :lint` puts every runfile into the one shape there is, then reports everything the runner would refuse — a
+syntax error, an unknown or misplaced property, a call to a function that does not exist, a name nothing binds,
+a `run` of a target that is not there, a line that [fails every time it runs](LANGUAGE-CHECK-RULES.md), shell the
+[shell checker](SHELL-CHECK-RULES.md) finds wrong — as
+`file:line:column`, which is the list your editor underlines. **It
+exits 0 only when every file is formatted and none of that is wrong**, so a file that passes runs without a
+parse-time error and opens with nothing underlined. `--check` writes nothing and fails on a file that needs
+formatting too, which is what a CI step wants.
+
+```bash
+$ run :lint --check
+runfiles/deploy.run: needs formatting
+runfiles/deploy.run:12:9: error: unknown function `exists`; did you mean `directory_exists` or `file_exists`?
+14 files checked: 1 needs formatting, 1 error in 1 file
+```
+
+A shell finding says what to write instead on the line under it. `run :lint` reports it and leaves the shell as
+you wrote it: only the layout of a file is ever rewritten.
+
+Formatting has no settings: one shape, everywhere. It reindents with tabs, spaces expressions, places blank
 lines, lays out `json` blocks, and leaves the three things that are not the language's to touch — strings, the
-text after `$ `, and `exec` bodies — exactly as written. It refuses a file that does not parse, and checks that
-its own output still means the same thing before writing it. `--check` reports what would change and exits 1,
-which is what a CI step wants.
+text after `$ `, and `exec` bodies — exactly as written. A file that does not parse is left alone, and the
+formatter checks that its output still means the same thing before writing it.
 
 ## Encrypted environment variables
 
@@ -813,33 +1048,48 @@ Keys live in the OS credential store — Keychain, Credential Manager, or Secret
 fallback. In CI, pass them as `RUNFILE_PRIVATE_KEYS` (newline-separated) and no credential store is involved.
 
 Decryption happens in memory; secrets never reach disk. The credential store is only touched when something
-actually decrypts, so a locked keyring never gets in the way of an unrelated target.
+actually decrypts, so a locked keyring never gets in the way of an unrelated target — and it is asked once in
+a run, however many of the targets that run calls decrypt. In watch mode each re-run asks again, so unlocking
+the keyring or adding a missing key takes effect on the next save.
 
 ## Editor support
 
-`runfile-lsp` ships beside `run` and gives you diagnostics, completion, formatting, go-to-definition and
-documentation on hover — from the same parser `run` itself uses, so your editor never disagrees with what will
-actually happen.
+`run :lsp` is a language server, so the binary you already have gives you diagnostics, completion, formatting,
+go-to-definition and documentation on hover — from the same parser `run` itself uses, so your editor never
+disagrees with what will actually happen. There is nothing extra to install.
+
+Diagnostics include every call to a function that does not exist and every name nothing has bound, underlined
+where it is written, with the name you probably meant. It is the check that stops a run before it starts, so it
+knows what the `_shared.run` above the file binds.
 
 Hover anything: a function shows its signature, what it does and a worked example; a property adds whether it
 may sit inside a block; `$`, `exec`, `run`, `retry`, `match` and the rest explain the line form itself.
 
+Completion knows where it is. At the start of a line it offers the keywords that fit there — `break` inside a
+loop, `case` inside a `match`, `end` only when something is open — and everywhere a value goes, the variables in
+scope: the file's own, its loop's, and those bound in the `_shared.run` above it. Inside `{{ … }}` on a `$` line
+it completes the same way, and in the rest of a shell line or an `exec` body it stays out of the way.
+
 Ctrl+click a `run <target>` to open that target's file, or a variable to jump to where it was bound — including
 into the `_shared.run` above it, which is the one definition you cannot find by reading the file in front of
 you.
 
-It also hands `$` lines and shell `exec` bodies to [shellcheck](https://www.shellcheck.net) when it is
-installed, mapping findings back to the lines you wrote.
+The shell in `$` lines and shell `exec` bodies is checked by the runner's own [shell checker](SHELL-CHECK-RULES.md),
+which reads each `{{ … }}` as the word it becomes — so nothing is reported against text nobody wrote, and there
+is nothing to install.
 
-**VS Code** — install the `.vsix` from the [latest release](https://github.com/JoaaoVerona/runfile/releases).
-You get a Run button on every target, a task provider, a sidebar tree, and shell lines coloured exactly as the
-same command in a `.sh` file. Set `"editor.formatOnSave": true` and saving formats.
+**VS Code** — install the `.vsix` from the [latest release](https://git.joaoverona.com/joaaoverona/runfile/releases).
+You get a Run button on every target, a task provider, a sidebar tree, shell lines coloured exactly as the
+same command in a `.sh` file, and a call to a function that does not exist coloured as an error as soon as you
+type its `(`. Set `"editor.formatOnSave": true` and saving formats.
 
 **JetBrains IDEs** read the same grammar: *Settings → Editor → TextMate Bundles*, add the `editors/vscode`
 directory from a checkout.
 
-**Zed, Neovim and Helix** use the tree-sitter grammar in `editors/tree-sitter`, with highlight queries
-included. For Neovim with nvim-treesitter:
+**Zed, Neovim and Helix** point their language-server configuration at `run` with the argument `:lsp` — in
+Neovim, `vim.lsp.config("runfile", { cmd = { "run", ":lsp" }, filetypes = { "runfile" } })` — and take the
+tree-sitter grammar in `editors/tree-sitter` for highlighting, with highlight queries included. For Neovim
+with nvim-treesitter:
 
 ```lua
 require("nvim-treesitter.parsers").get_parser_configs().runfile = {
@@ -905,7 +1155,7 @@ Shell is still there. It is just marked.
 | Windows | x86-64, arm64 |
 
 `$` lines use bash where it exists, Git Bash on Windows, and `sh` otherwise — so one file works everywhere. Set
-`.shell` to pin something else.
+`.shell` to pin one of the other POSIX shells, or name any other interpreter with `exec`.
 
 ## License
 

package/bin/run.js

@@ -2,10 +2,7 @@
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const KEY = process.platform + '-' + process.arch;
-// One launcher for both binaries, `run` and `runfile-lsp`: which one is
-// decided by this file's own name, so the second is a copy, not a second file.
-const NAME = path.basename(__filename, ".js");
-const EXE = process.platform === "win32" ? `${NAME}.exe` : NAME;
+const EXE = process.platform === "win32" ? "run.exe" : "run";
 const BINARIES = {
   "linux-x64": EXE,
   "linux-arm64": EXE,

package/package.json

@@ -1,7 +1,6 @@
 {
 	"bin": {
-		"run": "bin/run.js",
-		"runfile-lsp": "bin/runfile-lsp.js"
+		"run": "bin/run.js"
 	},
 	"description": "Runfile CLI — a cross-platform command runner with its own small language",
 	"engines": {
@@ -14,5 +13,5 @@
 	"license": "MIT",
 	"name": "@runfile/cli",
 	"repository": "https://github.com/JoaaoVerona/runfile",
-	"version": "1.1.6"
+	"version": "1.7.1"
 }

package/bin/runfile-lsp.js

@@ -1,32 +0,0 @@
-#!/usr/bin/env node
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const KEY = process.platform + '-' + process.arch;
-// One launcher for both binaries, `run` and `runfile-lsp`: which one is
-// decided by this file's own name, so the second is a copy, not a second file.
-const NAME = path.basename(__filename, ".js");
-const EXE = process.platform === "win32" ? `${NAME}.exe` : NAME;
-const BINARIES = {
-  "linux-x64": EXE,
-  "linux-arm64": EXE,
-  "darwin-arm64": EXE,
-  "darwin-x64": EXE,
-  "win32-x64": EXE,
-  "win32-arm64": EXE,
-};
-const bin = BINARIES[KEY];
-
-if (!bin) {
-	console.error(`run: unsupported platform ${KEY}. Supported: ${Object.keys(BINARIES).join(', ')}`);
-	process.exit(1);
-}
-
-const binPath = path.join(__dirname, KEY, bin);
-const result = spawnSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
-
-if (result.error) {
-	console.error(`run: failed to spawn ${binPath}: ${result.error.message}`);
-	process.exit(1);
-}
-
-process.exit(result.status == null ? 1 : result.status);