@runfile/cli 1.0.1 → 1.1.1

package/README.md

@@ -193,6 +193,39 @@ 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
 by the far end an hour later.
 
+### Reading JSON without jq
+
+`json_query` walks a path and answers with a **list**, where `[]` descends into every element the way jq's
+`.[]` does. What comes back is one of the language's own lists — something to loop over and count, not text to
+parse a second time.
+
+```sh
+# runfiles/audit/gate.run
+# Fail when a dependency has a high or critical vulnerability
+
+let report = ARG.report ? "osv.json"
+let severities = json_query(read_file(report), "results[].packages[].groups[].max_severity")
+let high = 0
+
+for severity in severities
+	if severity != "" && number(severity) >= 7
+		high = high + 1
+	end
+end
+
+print("High or critical:", high)
+
+if high != 0
+	exit(1)
+end
+```
+
+`json_get` reads one value at a path, and `json_keys` opens an object up — there is no map type, so without it
+an object is text and nothing more. `json_type` says what is at a path, which is the one question `json_get`
+cannot answer: it hands back `""` for a null and the compact text for an object. `json_format` is `jq .`, and
+`json_encode` goes the other way, turning a list into an array. Nothing here is a dependency your machine has
+to already have.
+
 ### Any language you have installed
 
 `exec <command>` runs that command with the block as its **stdin**, so a target can be a Python script, a Node
@@ -379,7 +412,7 @@ end
 `append`, `prepend`, `concat_lists`, `sort`, `reverse`, `unique`, `slice`, `flatten`, `zip`, `index_of` and
 `without`, beside `first`, `last`, `length` and `join`.
 
-There are 78 built-in functions — strings, lists, regex, paths, JSON, hashes, time, files. Your editor lists
+There are 83 built-in functions — strings, lists, regex, paths, JSON, hashes, time, files. Your editor lists
 them all with a description and an example; `run :list` is for targets, and the language server is for the
 language.
 
@@ -387,7 +420,7 @@ language.
 
 | Source | From |
 | --- | --- |
-| `ARG.name` | `--name=value` |
+| `ARG.name` | `--name=value`, or `--name value` |
 | `FLAG.name` | `--name` (a boolean) |
 | `ARGS` | positional arguments, as a list |
 | `ENV.NAME` | the environment |
@@ -399,8 +432,12 @@ language.
 let port = ARG.port ? ENV.PORT ? "3000"
 ```
 
-Arguments are `--key=value`. Writing `--key value` gives you a flag and a positional, because nothing declares
-which names take values — and if you meant an argument, the error says so.
+An argument takes its value two ways, `--key=value` and `--key value`, and nothing is declared to make the
+second one work: `run` walks the target's parsed tree, so it already knows `ARG.target` takes a value and
+`FLAG.force` does not. `--target aarch64` is the triple; `--force x` is a flag and a positional. Where a name
+is read both ways the bare `--name` is the flag, and `--name=value` is the argument. A value starting with a
+dash needs the `=` form — `--target --release` is refused rather than quietly setting the triple to
+`--release`.
 
 **A flag a target cannot read is an error**, not a typo you find out about later. `run` knows exactly what a
 target reads by walking its parsed tree, so `--forse` stops the run and points at `--help`:
@@ -423,8 +460,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**.
 
-Everything after a bare `--` is passed through untouched, flags included. That is how a wrapper forwards a
-command line it does not understand:
+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
+written, and forwarding a whole command line needs nothing special.
 
 ```sh
 # runfiles/aws.run
@@ -434,7 +472,15 @@ $ docker run --rm amazon/aws-cli {{ ARGS }}
 ```
 
 ```bash
-run aws -- s3api list-buckets --output json
+run aws s3api list-buckets --output json
+```
+
+Everything after a bare `--` is passed through untouched, whatever the target reads. That is how a wrapper
+forwards a word the target would otherwise claim — its own `--output`, or a `--help` meant for the command
+inside:
+
+```bash
+run aws -- s3api list-buckets --help
 ```
 
 ### Interpolation quotes itself
@@ -642,6 +688,9 @@ invoke `run` from.
 directory than hide it, `$HOME/runfiles/` and `$HOME/Runfiles/` are read too — but only one of the three may
 hold anything.
 
+**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.
 
@@ -659,6 +708,11 @@ error: `setup` has never been run
 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
+enforced and the file is not written. `RUNFILE_SKIP_PREPARE=1` is different: it turns the gate off on a machine
+whose state is still worth keeping, so a `setup` run under it is still recorded.
+
 ## Commands
 
 | Command | |

package/package.json

@@ -14,5 +14,5 @@
 	"license": "MIT",
 	"name": "@runfile/cli",
 	"repository": "https://github.com/JoaaoVerona/runfile",
-	"version": "1.0.1"
+	"version": "1.1.1"
 }