Module run 

keel run <script> [args…] — dispatch a program into its language front end.

The heavy lifting (bootstrap, import hook, adapters, discovery) lives in the Python and Node packages; run is only the dispatcher (dx-spec §1, Level 0):

• *.py → python3 -m keel run <script> [args…]
• *.{mjs,js,ts,cjs,…} → node --import keelrun/hook <script> [args…]
• a package.json, or a dir containing one → resolve its main, then the Node path
• any other dir → a conventional entry name (main.py, __main__.py, index.*), then — if exactly one Python or Node source file sits directly inside it — that file; ambiguous or empty is a precise error, never a guess
• anything else → a precise what/why/next error, exit 2

The child inherits the environment (so every KEEL_* var passes through); --disable layers KEEL_DISABLE=1 on top. The child’s exit code is the process’s exit code — wrapping is invisible on the success path.

Structs

RunPlan

The concrete plan: which interpreter to exec with which argv, and whether to disable Keel in the child. Pure data, so dispatch is unit-testable without spawning anything.

Enums

RunError

Why a target could not be dispatched — each rendered as what/why/next.

Functions

exec

Execute a RunPlan, inheriting the environment (so KEEL_* passes through). Returns the child’s exit code, or a rendered spawn error.

plan

Build the RunPlan for target and args. Reads the filesystem to classify the target and (for a package) to resolve its entry file.

run

The whole keel run command: plan, then exec. On a dispatch error render it; on success return the child’s exit code.