cancho-toolsjsonq 0.1.0
Look up one JSON Pointer (RFC 6901) in one strictly parsed JSON document; the value byte for byte, its kind, keys or length, and a parse error's position as data.
jsonq [--root DIR] [--pointer /a/0/b] [--keys | --length | --type | --exists] [--max-bytes N] [--format json|text] [FILE | -]- output
- one JSON document
- schema
- jsonq.v1
- reversibility
reversible-cheap- guarantees
deterministic,idempotent- concurrency
- read-only: it never writes, so any number may run at once
- confinement
beneath: with --root, paths are checked lexically against it and then opened beneath it one component at a time, following no symbolic link (path.symlink), so nothing outside the root is reachable through one; without it, a reader opens the path as given, links and all, and a writer still follows no link in the file's own name- reads the environment
- no
- reads the clock
- no
- compiler
- de4e52fd8180
- for an agent
- SKILL.md (
jsonq skill)
Authority
Derived by cancho authority from the source, embedded in the binary, and checked against tools.toml's ceiling in CI. Every label is bounded.
- args
- dir_read
- err_write
- file_read
- fs_read("")
- heap
- io_read
- io_write
What the row cannot say:
- path extent: a path from the command line is checked at run time, so the row says fs_read("")
- what a symlink reaches
- what standard output carries
- resource use beyond the tool's own caps (memory, wall time)
- per-invocation behaviour such as --dry-run, which the row cannot see
Operands
| Operand | Role | How many | Meaning |
|---|---|---|---|
FILE | path-read | 0 to 1 | the document, - or nothing reads standard input |
Flags
| Flag | Kind | Role | Default | Meaning |
|---|---|---|---|---|
--root | path | root | resolve FILE relative to this directory and refuse paths outside it | |
--pointer -p | any | none | the JSON Pointer (RFC 6901) to look up, empty is the whole document | |
--keys | bool | none | answer the keys of the object at the pointer, in document order | |
--length | bool | none | answer the number of elements, pairs, or bytes of a string at the pointer | |
--type | bool | none | answer only the kind of the value at the pointer | |
--exists | bool | none | answer whether the pointer names anything, true or false, never an error | |
--max-bytes | nat | none | 4194304 | the largest document accepted (ceiling 33554432), memory is about 25 times this |
--format | choice:json/text | none | json | json for a program, text for a person |
Limits
| Limit | Default | Ceiling |
|---|---|---|
max-bytes | 4,194,304 | 33,554,432 |
Exit codes
| Code | Name | Meaning |
|---|---|---|
| 0 | SUCCESS | what was asked was done; zero matches is success |
| 1 | GENERAL_ERROR | the operating system failed mid-operation, or the tool caught a bug in itself |
| 2 | INVALID_ARGS | the invocation is malformed or names something of the wrong kind; nothing was read |
| 3 | NOT_FOUND | a named input does not exist |
| 4 | PERMISSION_DENIED | the operating system refused, or the tool's own confinement did |
| 8 | PRECONDITION_FAILED | the answer is no, or a limit was reached |
Rules (24)
Match on rule, not on the message. A retry repair is an argv that can be run as it stands, and never widens what the tool may touch.
| Rule | Exit | Repair | When |
|---|---|---|---|
args.unknown-flag | 2 | sometimes | a flag that is not in the tool's table |
args.missing-value | 2 | never | a flag that takes a value was given none |
args.bad-value | 2 | never | a flag's value is not of the flag's kind |
args.unexpected-value | 2 | never | a flag that takes no value was given one |
args.duplicate-flag | 2 | never | the same flag was given twice |
args.conflict | 2 | never | two flags that exclude each other were both given |
args.too-many-operands | 2 | never | more operands than the tool takes |
path.empty | 2 | never | an empty path |
path.dotdot | 2 | sometimes | a path with a `..` component |
path.absolute | 2 | always | an absolute path where one relative to --root is wanted |
path.outside-root | 4 | never | an absolute path that is not under --root |
path.too-long | 2 | never | a path longer than 4096 bytes |
path.symlink | 4 | never | a path that runs through a symbolic link, which the tool does not follow |
io.not-found | 3 | never | a named input does not exist |
io.not-a-directory | 3 | never | a path runs through something that is not a directory |
io.is-a-directory | 2 | never | a directory where a file is wanted |
io.permission-denied | 4 | never | the operating system refused access |
io.read-failed | 1 | never | the operating system failed a read |
limit.input-too-large | 8 | sometimes | an input longer than --max-bytes |
parse.json | 8 | never | the input is not one valid JSON document |
query.bad-pointer | 2 | never | a JSON Pointer that is not RFC 6901 syntax |
query.no-such-path | 3 | never | a JSON Pointer that names nothing in the document |
query.wrong-kind | 8 | never | the value at the pointer is not of the kind the query needs |
query.unsupported-syntax | 2 | never | a query this tool refuses to grow to answer |
Evidence
each gate is a test in cancho-tools/tests/conformance, run by CI on the commit this binary was built from:
- M1 schema conformance
- M2 determinism
- M3 rule coverage and hint soundness
- M4 fault injection
- M5 differential against GNU
- M6 authority
- M7 mutation behaviour
- M8 confinement
- M9 memory flatness
Agent in the loop: not run: no claim that this tool is more agent-friendly than the incumbents is made (cancho docs/agent-toolbox.md section 7.2).