Oko
Oko/Docs

Command reference

oko planning check

Checks a work plan before it runs. A plan is a graph of steps; each step names the steps it follows (`after`), the conditions it needs, the command that does it (`run`) and the effect a test confirms (`effect`). A condition is a command that reads a product's state and holds when it succeeds; a condition that holds only after an earlier step names that step in `produced_by`, and that step must come before it and test its effect. Every other condition is asked now. The plan is admitted only when every condition holds or is produced.

Invocation#

Command
oko planning check --plan FILE

Inputs and options#

  • --plan names a JSON file `{"steps": [{"id", "after": [ids], "conditions": [{"name", "read": [argv], "produced_by"}], "run": [argv], "effect": {"name", "test": [argv]}}]}`. Commands are argv lists, never shell lines; no other key is accepted.

Output and state effect#

  • Runs each read as an announced wait and prints `{admitted, steps: [{id, conditions: [{name, state, …}]}]}`, each condition `met` or `unmet` with the read's `observed` status, stdout and stderr, `produced` with the step and effect that make it hold, or `unverifiable` with the cause; exits 0 only when the plan is admitted.

Refusals and safe exits#

  • `oko planning check requires --plan <text>` (exit 2); `the plan <path> cannot be read: <error>`; `the plan <path> is not a plan: <error>`; `the plan declares step <id> twice`; `step <id> names no command to run`; `step <id> names no test of its effect <name>`; `step <id> condition <name> names no read`; `step <id> follows <earlier>, which the plan does not hold`; `the steps <ids> follow each other in a cycle`; after the report, `the plan is not admitted: step <id> condition <name> does not hold (<status>: <stderr>); step <id> condition <name> cannot be checked: <cause>` naming every one.

CLI reference#