@runfile/cli 1.8.0 → 1.9.0

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
 
@@ -545,7 +552,7 @@ run deploy [--env=<value>] --token=<value> [--force]
   Deploy to an environment.
 
 Arguments
-  --env=<value>                 defaults to staging
+  --env=<value>                 defaults to staging; one of staging, production
   --token=<value>               required
   --force                       off unless passed
 
@@ -554,9 +561,21 @@ 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**. 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.
+default. A `one_of` with its options written out, `one_of(ARG.env ? "staging", "staging", "production")`, is
+what lists the values a name takes. `run --stdin-args deploy` asks for the same list, in the same order,
+**before anything runs**, and shows the same options; the target's own `one_of` is still what refuses a wrong
+answer. 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.
+
+A target that reads `ARGS` is asked for its positionals too, when none were given: one line, split the way a
+command line is, so `"two words"` stays one. Enter passes none, which is what a wrapper usually wants. A
+`confirm()` the target reaches is asked the same way. The answers come from stdin whether or not it is a
+terminal, so they can be piped in. In CI nothing is asked unless stdin is a terminal.
+
+```bash
+$ run --stdin-args release
+[runfile] ARGS (one of major, minor, patch): minor
+```
 
 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
@@ -594,6 +613,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;
@@ -704,7 +738,8 @@ forgives it. `confirm("…")` asks, and stops the whole run if the answer is no.
 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.
+skipped by `-y`, in CI, and under `--dry-run`, where there is nothing to approve. It is asked on a terminal, or
+under `--stdin-args` on whatever stdin is: that flag is what says somebody answers there.
 
 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.
@@ -950,6 +985,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
@@ -980,7 +1022,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
 
@@ -1011,15 +1054,15 @@ 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 |
 
 | Flag | |
 | --- | --- |
 | `-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 |
+| `--stdin-args` | Prompt for every input the target reads, positionals included, before it runs, and answer its `confirm()` on stdin too |
+| `--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 |
@@ -1048,7 +1091,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
 
@@ -1066,13 +1110,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
 
@@ -1126,7 +1180,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.8.0"
+	"version": "1.9.0"
 }