@runfile/cli 1.7.2 → 1.8.5

package/README.md

@@ -59,7 +59,8 @@ irm https://git.joaoverona.com/joaaoverona/runfile/releases/download/latest/inst
 
 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.
+a release other than the latest (`v1.8.4`, or `1.8.4`), and `RUNFILE_INSTALL_DIR` chooses where it goes. Both
+are read by the shell running the script, so that is where they go: `curl -fsSL … | RUNFILE_VERSION=v1.8.4 sh`.
 
 ```bash
 run :init             # creates runfiles/ with an example
@@ -74,8 +75,9 @@ run :completions install bash   # tab-completion (or zsh, fish, powershell)
 ```
 
 Runner flags go **before** the target name; everything after it belongs to the target. `run build --dry-run`
-passes `--dry-run` to `build` as `FLAG.dry-run` and runs it for real — so the position is the whole meaning.
-`run` warns when a target is handed a flag it never reads, which is what catches that.
+hands `--dry-run` to `build` and runs it for real — as `FLAG.dry-run` if `build` reads that, or in `ARGS`, its
+positional arguments, if it reads those — so the position is the whole meaning. A target that reads neither
+refuses the flag rather than running without it, which is what catches a `--dry-run` on the wrong side.
 
 In CI, the setup action installs `run` and puts it on PATH, so every step after it is a target name:
 
@@ -88,7 +90,9 @@ In CI, the setup action installs `run` and puts it on PATH, so every step after
 ```
 
 `@v1` is the major alias, moved to each release as it ships — so a fix arrives without editing every
-workflow, and a new major never arrives unannounced. Pin `@v1.0.0` instead to hold one exact version.
+workflow, and a new major never arrives unannounced. Pin `@v1.8.4`, or a commit SHA, instead to hold one exact
+version: the action installs the release its own ref belongs to, so the pin holds the binary as well as the
+action. `version:` overrides that — a tag such as `v1.8.4`, or `latest` for whatever was published last.
 
 ## What a runfile looks like
 
@@ -341,8 +345,11 @@ confirm("Deploy to production?")
 $ terraform apply -auto-approve
 ```
 
-The temp file is deleted when the run ends, however it ends — including a failure half-way, which is exactly
-when a decoded credential must not be left behind.
+The temp file is deleted when the run ends, however it ends — including a failure half-way, or a SIGTERM/SIGHUP,
+which is exactly when a decoded credential must not be left behind — and it is created readable only by you
+(`0600`). The runner also keeps interpolated secrets out of **its own** output: a failed command and a
+`.logging` line show `{{ ENV.TOKEN }}` where the value would be, not the value, so a secret does not land in
+terminal scrollback or a CI log.
 
 ### A pre-commit hook
 
@@ -594,6 +601,21 @@ $ cp {{ ARG.src }} {{ ARG.dest }}
 left to quote: the substitution already did it. The same rule holds one layer up inside a `json` block, where
 an interpolation becomes one JSON value.
 
+Where the shell around an interpolation is quoted already — a message in `"…"`, a heredoc, a command string for
+another shell — the value is written for those quotes too, so it stays text whatever it holds:
+
+```sh
+$ ssh deploy@host "cd {{ ARG.dir }} && ./restart"
+```
+
+The remote shell is handed `cd 'my dir' && ./restart`, quoted for it, and a `$( )` or a backtick in the value
+is text to both shells. A value that would end the heredoc or the shell comment it sits in is refused rather
+than written.
+
+A list becomes one argument per item, so give it a word of its own rather than gluing text onto its end —
+`{{ files }} suffix`, not `{{ files }}suffix`. An empty list is no words at all, so `rm -rf {{ dirs }}/cache`
+with an empty `dirs` is `rm -rf /cache`; `run :lint` flags that glued shape.
+
 ### Asking whether a command worked
 
 A `$` run may stand as a condition or as a `match` subject. The condition is true when the command exits 0;
@@ -678,9 +700,30 @@ end
 
 ### Stopping early
 
-`exit()` ends the run with a status; `error("…")` fails with a message; `confirm("…")` asks, and stops if the
-answer is no. Nothing catches any of them: not a `?` fallback, not `.ignore-errors`. A target may forgive a
-command that failed, but being told to stop is not that.
+`exit()` ends the target it is written in, with a status — 0 when none is given. Nothing inside that target
+catches it: not a `?` fallback, not `.ignore-errors`, not a `retry`. A target may forgive a command that failed,
+but being told to stop is not that. It is also how a helper finishes early:
+
+```sh
+# runfiles/_setup-build.run
+# Prepare the toolchain; Linux needs nothing
+
+if RUN.os == "linux"
+	print("no setup needed")
+	exit()
+end
+
+$ ./scripts/setup-toolchain.sh
+```
+
+To a target that ran it, the status is how it went — exactly what `$ run _setup-build` would make of it. After a
+0, the `run _setup-build` line is done and the next line runs. Anything else fails that `run` line, like a
+command that failed: `.ignore-errors` forgives it, `retry` has another go, `code_of` scores it, and if nothing
+handles it, the whole run ends with that status.
+
+`error("…")` fails with a message, the way a command fails, so a `?` falls back from it and `.ignore-errors`
+forgives it. `confirm("…")` asks, and stops the whole run if the answer is no. Nothing catches that, not even a
+target that ran this one.
 
 `confirm` is a function rather than a property, so the question can depend on what is about to happen — and is
 skipped by `-y`, in CI, and under `--dry-run`, where there is nothing to approve.
@@ -929,6 +972,13 @@ runfiles/api/deploy.run     → run api:deploy
 Inside a subproject, `run build` means *that* subproject's `build` — so a file reads the same wherever you
 invoke `run` from.
 
+**The `runfiles/` the walk finds has to be yours.** A directory any account can write — `/tmp`, or the root of
+a Windows drive — would otherwise hand its targets to every directory beneath it that has none of its own. So
+it must belong to you, to the machine's administrators, or to whoever owns the directory you started in, which
+keeps working inside a colleague's checkout as deliberate as it always was. A directory meant to be shared
+between accounts is trusted by naming it, or the project holding it, in `RUNFILE_SAFE_DIRECTORIES` — paths
+separated the way `PATH` separates them, or `*` for all.
+
 `$HOME/.runfiles/` holds machine-wide targets, available in every project. If you would rather see the
 directory than hide it, `$HOME/runfiles/` and `$HOME/Runfiles/` are read too — but only one of the three may
 hold anything. `run :list` puts them first, under `global:`: they are the part of the listing you cannot see
@@ -959,7 +1009,8 @@ project's lint leaves the directory out otherwise.
 what is checked in and reviewable. This is also why nothing has to be cleaned up after a job.
 
 Everything relative — `.env-file`, `.add-path`, `glob`, `read_file`, `{{ RUN.parent }}`, the working directory
-— resolves against **the parent of `runfiles/`**. One anchor, one rule.
+— resolves against **the parent of `runfiles/`**. One anchor, one rule. An absolute path is taken as written,
+and an absolute `glob` pattern answers with absolute paths.
 
 ## Setup targets
 
@@ -972,8 +1023,9 @@ error: `setup` has never been run
     run setup
 ```
 
-It re-triggers when `setup.run` itself changes, so a new dependency is not silently missed. `--dry-run` is
-exempt, CI is exempt, and `RUNFILE_SKIP_PREPARE=1` bypasses it.
+Only a setup that succeeded counts: one that failed, or ended with a non-zero `exit()`, leaves the gate shut. It
+re-triggers when `setup.run` itself changes, so a new dependency is not silently missed. `--dry-run` is exempt,
+CI is exempt, and `RUNFILE_SKIP_PREPARE=1` bypasses it.
 
 The record lives in `state.json` in the platform state directory. In CI there is none: a runner is built and
 thrown away, so there is no earlier session whose `setup` this one could be relying on — the gate is not
@@ -989,7 +1041,7 @@ whose state is still worth keeping, so a `setup` run under it is still recorded.
 | `run :init` | Create `runfiles/` with an example |
 | `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 :completions <command> <shell>` | `install`, `uninstall` or `output` a completion script for `bash`, `zsh`, `fish` or `powershell` — after upgrading from 1.8.2 or older, `install bash` again: the installed script is a copy |
 | `run :generate <editor>` | Task files for `zed`, `jetbrains` or `vscode`, merged into what is there |
 | `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 |
 
@@ -997,7 +1049,7 @@ whose state is still worth keeping, so a `setup` run under it is still recorded.
 | --- | --- |
 | `-y`, `--yes` | Skip confirmation prompts |
 | `--stdin-args` | Prompt for every input the target reads, before it runs |
-| `--dry-run` | Print what would run, without running it |
+| `--dry-run` | Print what would run, without running it — a preview reads no files outside the project, probes none, and never unlocks the credential store |
 | `--dir <path>` | Start discovery somewhere else |
 | `-h`, `--help` | Show the help for `run` or any of its commands |
 | `-v`, `--version` | Print the version |
@@ -1026,7 +1078,8 @@ 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. A file that does not parse is left alone, and the
-formatter checks that its output still means the same thing before writing it.
+formatter checks that its output still means the same thing before writing it. The file is then replaced in one
+step, keeping its permissions, so an interrupted write never leaves half of one behind.
 
 ## Encrypted environment variables
 
@@ -1044,13 +1097,23 @@ run :env get .env.production KEY       # decrypts on read
 run :env rotate .env.production        # re-encrypt under a new key
 ```
 
+`set` encrypts under the public key the file itself records — `:env init` writes it at the top — and never
+falls back to plaintext: for a file that records none, `--key <prefix>` names the key to use, and `--plain`
+stores the value as it is.
+
 Keys live in the OS credential store — Keychain, Credential Manager, or Secret Service with a keyutils
 fallback. In CI, pass them as `RUNFILE_PRIVATE_KEYS` (newline-separated) and no credential store is involved.
 
+Only a value a `.env` file holds is decrypted — the one place an `encrypted:` value is the author's own. A
+ciphertext arriving any other way (exported in the caller's shell, or copied into `.env.X = {{ ARG.x }}` from
+data an outsider controls) is passed through unchanged, never decrypted with the run's keys, so it cannot be
+turned back into plaintext by a target that merely echoes a variable.
+
 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 — 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.
+the keyring or adding a missing key takes effect on the next save. `--dry-run` never touches it: a preview
+reads no `.env` files and asks for no key.
 
 ## Editor support
 
@@ -1104,7 +1167,8 @@ vim.filetype.add({ extension = { run = "runfile" } })
 ```
 
 `run :generate zed` writes every target into `.zed/tasks.json`, and `run :generate jetbrains` into
-`.idea/runConfigurations/`; both leave entries you wrote yourself alone and replace only their own.
+`.idea/runConfigurations/`; both leave entries you wrote yourself alone and replace only their own, and a file
+they cannot read is left as it is rather than written over.
 
 ## Why a language
 

package/package.json

@@ -13,5 +13,5 @@
 	"license": "MIT",
 	"name": "@runfile/cli",
 	"repository": "https://github.com/JoaaoVerona/runfile",
-	"version": "1.7.2"
+	"version": "1.8.5"
 }