oko defects operations check

Invocation#

oko defects operations check (--command "PROGRAM WORDS" | --tool NAME) [--session SESSION] [--json]

Inputs and options#

• A functionality is what an open defect breaks, named once for every session: a command path, the program and its command words as its CLI spells them (--command "oko asks ask"), or a harness tool that is not a shell (--tool NAME). A shell call reaches a command path when one of its commands runs that program, by name and from any directory, and its words that are not options begin with the command words, in order. Options are set aside wherever they stand. A program whose global options are declared (Oko's defects/operations/grammar/grammars.json, each with the page it is taken from) is read by that grammar first: its global options that take a value in the next word step over that word, so it is never a command word, and its subcommand is the first word after them. A program the declaration marks as a wrapper (`wraps`, below) is stepped over with its options and the assignments after it, so the program it runs is the one read: env -u X HOME=/h git fetch reaches git fetch. That declaration is the only one: Oko publishes it verbatim beside the register as <register>.grammars.json (defects.grammars.json) at every write of the register and at oko defects snapshot, and Tama's admission reads that file, so both read a call alike; Tama refuses a call that may run a bound path when the register exists and the published declaration is missing or unreadable, naming the file and oko defects snapshot. git (git(1): -C, -c, --git-dir, --work-tree, --namespace, --config-env) and cargo (cargo(1): --explain, --color, -C, --config, -Z) are declared; any other program is read with its options set aside. --help is read like any other argument, since it can be an option's value or a directory: a call that runs the path with it reaches the path, while the program's own help (git --help, git help fetch) is another path. oko asks ask --from x --question y, oko asks ask --help, ~/.stado/bin/oko asks ask and true && oko asks ask all reach oko asks ask; git -C <repository> fetch, git -C --help fetch and git -c fetch.prune=true fetch reach git fetch; cargo --color always build reaches cargo build; oko asks list, git --help, git help fetch, git log --grep fetch, git -C fetch status, git --no-pager log fetch and cargo --color build check do not. oko defects operations check reads a call the same way Tama's admission does.
• A program the declaration marks as a wrapper (env, from GNU coreutils' env manual) runs the program after its options, so the call is read from that program by the role the declaration gives each option: a value option's value is stepped over (-C, --chdir, -P, -a, --argv0), an unset option's value is a name the program's environment loses (-u, --unset), a clear option starts that environment empty (-i, --ignore-environment, -), whether the value stands in the next word, after `=`, or in the rest of a bundle of short options (`-uHOME`), and `--` ends the options. With assignmentOperands, every operand holding `=` before the program sets a variable whatever its name, since env accepts any name without `=` or NUL, the empty one included: env 'A-B=x' git fetch and env =x git fetch reach git fetch. Its split-string options (-S, --split-string) are not values set aside: their value is split into words by env's own rules (env.c build_argv: only space, tab, newline, vertical tab, form feed and carriage return separate outside quotes; single and double quotes group, and an apostrophe inside double quotes is a character; the manual's escapes; `\c` and a leading `#` end the string; `${NAME}` adds a present variable's value, an empty one included, and nothing at all, not even an empty word, for an absent one) and read in their place, so env -S "git fetch", env --split-string='git fetch', env -vS'git fetch', env -S "git fetch \"it's\"" and env -i env -S '${ABSENT} git fetch' reach git fetch, while env -i EMPTY= env -S '"${EMPTY}" git fetch' runs an empty program; a split string env refuses, such as `$NAME` without braces, runs nothing. `${NAME}` expands in the environment the executed env was started with, which is the one the call builds: the shell's assignments before the command (a name of letters, digits and underscores not beginning with a digit) and every outer env's -i, -u and assignments over the inspecting process's own, so FOO=git env -S '${FOO} fetch' and env FOO=git env -S '${FOO} fetch' reach git fetch, while FOO=git env -u FOO env -S '${FOO}k fetch' does not. Where the shell itself expands (a `$` or backtick unquoted or in double quotes, not escaped), the value is one only the running shell knows: a split string expanding a variable set so (FOO=$GIT, a command substitution) is refused by Tama's admission, by oko defects operations check and by the native check with "which program this call runs cannot be read" naming the variable, never read as running nothing or anything. A single-quoted or escaped `$` is a character: FOO='$GIT' sets the four characters $GIT, so FOO='$GIT' env -S '${FOO} fetch' is a string env refuses and runs nothing. Each command's words are read as the shell hands them to the program, quotes removed, so git "fetch" and git -C "/path with spaces" fetch reach git fetch, and the command line handed to a shell after -c is read the same way. Oko's check and Tama's admission read a call by these same rules from the one published declaration; a call whose first program is no declared wrapper is read from its own words, without copying them.
• Oko's check, the native check and Tama's admission read a whole call by one walk (Oko's defects/operations/grammar/reading, which Tama carries as its command_path/reading): the call is parsed by the bash grammar (tree-sitter-bash), and every simple command its syntax tree holds is one command, wherever it stands — in a list, a pipeline, a subshell, a group, an if, while or case body, or a command or process substitution at any depth, inside double quotes or a here-document included. Comments, reserved words and operators are syntax, never a command or a word of one: printf ok # ; git fetch runs no Git, and 'if' fetch runs a program named if. A command's words are the assignments written before its name, its name and its arguments, in order; redirections are not words. A line the grammar cannot parse (a quote never closed) is refused naming it. A program /etc/shells declares a shell runs its command string, found by the invocation grammar grammars.json declares for it (sh, dash, bash, zsh, ksh: options first, short bundles letter by letter, long ones whole, -o, +o, -O, --rcfile and --init-file stepping over their value, -- or - ending them, and with -c the first operand is the command string), parsed the same way in turn; a shell the machine declares with no declared grammar is refused naming it. So true && git fetch, (git fetch), true && { git fetch; }, if git fetch; then true; fi, echo "$(git fetch)", sh -c 'git fetch' and bash --norc -c 'git fetch' reach git fetch in all three. Each word follows the Open Group's Quoting rules: inside double quotes a backslash removes itself before $, `, ", \ and a newline and stays before anything else, so FOO=git env -S "\${FOO} fetch" reaches git fetch. A word only the running shell knows is neither a match nor a miss: a program ($GIT fetch), a word standing where a command word is compared (git $SUB), a split string the shell computes (env -S "$CMD") and a shell's command line the shell computes (sh -c "$CMD") are refused with "cannot be read" and what was unread. Every character of a split word remembers the expansion it came from, the value it expanded to and the whole environment it expanded in, so expanding a variable to the same value in the same environment from text that state produced (X='-S${X}' env -S '${X}') is refused as splitting without end, while the same name rebound by a later env (X='-S${X}' env -S 'X=git env ${X} fetch', which runs git fetch), the same value where a later env changed another variable it expands (X='-S${Y}' with a later Y=git), and two finite split options written alike (env -S 'printf x' -S 'printf x') are read as written. env -S 'printf %s x;git fetch' runs printf with a literal semicolon, not a second command. A command whose first program is no declared wrapper is read from its own words, without building the words that remember expansions.
• Exactly one of --command and --tool names the functionality. The --command text (and each --blocks of oko defects record) is read into words as the shell would hand them to the program, so a quoted word stays one word and is then refused as not a single command word, and a quote never closed is refused by name instead of being split on spaces. A program is named without its directory, a command path holds no option, and a shell tool (bash, Bash, run_shell_command, exec_command, as Oko's shell.json declares them) cannot be bound as a tool: binding it would refuse every command of every session.
• Every open defect is sorted in one of three ways: it binds the functionality it breaks (bind), names the open defect it is a symptom of (root), or states why no call could reach what it breaks (none). oko defects record requires one of --blocks "PROGRAM WORDS" (repeatable; each is bound with the evidence as its cause), --root ROOT and --blocks-nothing REASON, and the native record action the same blocks, root and blocks_nothing fields. A defect another Oko path writes unsorted (an operator moment, a stall, a loop of waits) is handed out by oko work right after the build-first pool until it is sorted. Quoting an output with record --observed or defects observed binds nothing: the call that printed it may be any command.
• The native defects operations action accepts the same verbs with identity {command: [words]} or {tool: name}. Oko Desktop → Defects → Functionality blocked by defects reads, binds, sorts, checks and withdraws the same records through the resident native API.
• --command takes the command path or a fuller call of it: check --command "oko asks ask --question x" reads as oko asks ask. --session names the asking session; a defect it owns refuses it unless its declared work for its current instruction is that defect.

Output and state effect#

• Returns {allowed, allowedWhileDeclared, defects, owned, verify, allOpenDefectsSorted, unsorted}. allowed is true only when no open defect refuses the call to any declaration of the session. allowedWhileDeclared is true when the only defects that refuse it are ones the session owns: Tama admits the owner only while its declared work for the operator's current instruction is one of them (each owned row's admittedWhile names `tama task scope set --session <owner> --defect <id>`), and Oko does not hold that declaration, so it answers the condition instead of allowed. defects lists the open defects that refuse the functionality to the session, each with its title, owner, functionality, cause, repair plan and the deepest open root it is a symptom of (null when it is its own cause); owned lists those the session owns. verify lists the symptoms whose root has closed: they no longer refuse the call, so the first call proves whether the root's repair repaired them. unsorted lists every open defect sorted in no way, each with the three commands that sort it, exactly as Tama decides.
• A check that is not allowed prints the full report and exits unsuccessfully, an owner-only one included; an allowed check does not prove the functionality works. Oko Desktop -> Defects -> Operations shows the same three answers: allowed, refused unless declared, refused.
• Each owned row carries openTrial: the trial the owner named with oko defects operations trial whose result is not recorded, or null when none is named.

Refusals and safe exits#

• open defects block this functionality; it stays refused until they are fixed or withdrawn: <matches>
• this session owns the open defects that block this functionality, so Tama admits it only while its declared work for the current instruction is one of them: <owned>
• An invalid functionality or unreadable register is refused with its cause. In Tama, a missing or malformed snapshot or publication receipt, and a receipt that does not identify the current register and the opened snapshot, refuse every ordinary tool with TAMA_HOOK_INFRASTRUCTURE and the actual path. Mismatches name both published and observed file identities. Equal or newer modification timestamps cannot authorize a stale snapshot. The exact standalone `oko defects snapshot` or `oko defects snapshot --json` command remains subject to ordinary hooks and can regenerate this derived publication; combining it with another shell command grants no recovery admission.

CLI reference#

• View the complete oko command tree