cancho-toolspeek 0.1.0
Read a range of a file -- lines with numbers and offsets, or bytes -- with its size, a binary flag and a cursor to the rest; head, tail, sed -n, cat -n and wc -l in one call.
peek [--root DIR] [--lines A:B | --bytes A:B] [--max-bytes N] [--max-line-bytes N] [--count-lines] [--format json|text] PATH- output
- one JSON document
- schema
- peek.v1
- reversibility
reversible-cheap- guarantees
deterministic,idempotent,bounded_memory- 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 (
peek 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_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 |
|---|---|---|---|
PATH | path-read | 1 | the file to read |
Flags
| Flag | Kind | Role | Default | Meaning |
|---|---|---|---|---|
--root | path | root | resolve PATH relative to this directory and refuse paths outside it | |
--lines -n | text | none | 1:100 | the lines A:B to return, 1-based and inclusive, A: runs to the end of the file or the budget |
--bytes -c | text | none | the bytes A:B to return, 0-based and end-exclusive | |
--max-bytes | nat | none | 65536 | the most text returned, past it the answer is truncated with a next cursor (ceiling 16777216) |
--max-line-bytes | nat | none | 1048576 | the longest line returned whole, a longer one is limit.line-too-long (ceiling 16777216) |
--count-lines | bool | none | read to the end and report total_lines | |
--format | choice:json/text | none | json | json for a program, text (cat -n) for a person |
Limits
| Limit | Default | Ceiling |
|---|---|---|
max-bytes | 65,536 | 16,777,216 |
max-line-bytes | 1,048,576 | 16,777,216 |
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 (20)
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.missing-operand | 2 | never | an operand the tool needs was not 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.line-too-long | 8 | sometimes | a line longer than --max-line-bytes |
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).