@runfile/cli 1.8.5 → 1.9.3

package/README.md

@@ -552,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
 
@@ -561,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
@@ -616,6 +628,10 @@ A list becomes one argument per item, so give it a word of its own rather than g
 `{{ 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.
 
+An `exec` line is read by no shell: the runner splits it into the program and its arguments itself, and writes
+each value for that, so a value there arrives the same way — one argument, or one per item of a list, quotes
+and all.
+
 ### 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;
@@ -726,7 +742,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.
@@ -796,7 +813,7 @@ Set at the top of the file, or inside a block where marked.
 | --- | --- | :-: | :-: |
 | `.shell` | Which POSIX shell `$` lines use. | | |
 | `.env.NAME` | Set an environment variable. | ✅ | |
-| `.workdir` | Where commands run. | ✅ | |
+| `.workdir` | Where commands run, and what every relative path below it resolves against. | ✅ | |
 | `.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. | ✅ | |
@@ -982,15 +999,23 @@ 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
-by looking at the project.
+by looking at the project. That holds for `~/runfiles` too, though it sits where the walk up from anywhere in
+your home directory looks: it is never taken for a project, so from a directory with no `runfiles/` of its
+own you get your global targets — and not every project under your home as a subproject.
+
+A machine-wide target's `runfiles/` parent is your home directory, so that is where its commands run. One that
+acts on the project in front of you says so with `.workdir = RUN.cwd` — and every relative path follows it, so
+`read_file("package.json")` and `.env-file = ".env"` read the project's files, not your home's. A `_shared.run`
+in the machine-wide directory can say it once for all of them.
 
-A machine-wide target can say where it belongs, so one directory can hold work for several places at once:
+A machine-wide target can also say where it belongs, so one directory can hold work for several places at once:
 
 ```sh
 # ~/.runfiles/deploy.run
 # Ship the current branch
 
 .only-in-directories = ["~/work/acme", "~/work/zed"]
+.workdir = RUN.cwd
 
 $ ./scripts/ship
 ```
@@ -1008,9 +1033,16 @@ 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.
 
-Everything relative — `.env-file`, `.add-path`, `glob`, `read_file`, `{{ RUN.parent }}`, the working directory
-— 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.
+Everything relative — a command, `glob`, `read_file` and the other file functions, `.env-file`, `.add-path`,
+`.watch`, and `.workdir` itself — resolves against **the working directory in effect where it is written**. One
+rule, so a path names the same file to the language as it does to the shell on the next line. The working
+directory starts at the parent of `runfiles/`, which is `{{ RUN.parent }}`, and a `.workdir` moves it from its
+own line down to the end of its block. A nested one is relative to the one around it, the way `cd` is:
+`.workdir = "src"` inside a block under `.workdir = "web"` is `web/src`. A path written *above* a `.workdir`
+keeps the directory it was written in, so `.add-path = "web/node_modules/.bin"` above `.workdir = "web"` still
+names the subproject's tools. An absolute path is taken as written, and an absolute `glob` pattern answers with
+absolute paths. `RUN.parent` and `RUN.cwd` never move: the first is the project, the second is where you typed
+`run`.
 
 ## Setup targets
 
@@ -1048,7 +1080,7 @@ whose state is still worth keeping, so a `setup` run under it is still recorded.
 | Flag | |
 | --- | --- |
 | `-y`, `--yes` | Skip confirmation prompts |
-| `--stdin-args` | Prompt for every input the target reads, before it runs |
+| `--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 |

package/package.json

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