@runfile/cli 1.0.1 → 1.1.0

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.
 
@@ -642,6 +675,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 +695,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.0"
 }