feat(cli): author a CLI in code, by pointer, or as a script by zechengz · Pull Request #712 · strukto-ai/mirage

zechengz · 2026-08-05T10:47:18Z

Item 2 of #705, authoring your own CLI. Three steps on one branch.

Summary

One invocation record. handle_cli builds a frozen CLIInvocation per
line (argv, stdin, env, config, paths, texts, flags) and every
handler tier renders it, so fn(config, paths, *texts, **flags) becomes
fn(inv) in both languages and the stdin-kwarg clobber is gone structurally.
cli: points at code, the way resource: does: a builtin or registered
name, module:ATTR, ./file.py:ATTR, or the mirage.clis entry-point group
(python; TypeScript keeps its named registry, matching its resources).
A CLI can be a script. CLISpec.script (yaml script:) embeds an ordinary
.py/.js/.mjs program at load and a workspace runtime runs it:
runtime_for_language takes the first entry speaking the script's language, or
runtime: pins one. The program gets what a native binary would get, argv
verbatim after the head word, piped stdin, and the install config as
MIRAGE_CONFIG json; its exit code becomes the line's $?. That makes a
script CLI a zero-SDK plugin: one yaml entry plus a program that imports
nothing from mirage.
Both tiers sit behind one front door (help, unknown verbs and declared-flag
validation all run before either handler) and convert their outcome through
one run_output/runOutput mapping, now also used by python3 and node.
monty gained a stdin global; it dropped RunArgs.stdin before this.

Test plan

pytest green; core, node and server tsc and vitest green; pre-commit clean;
spec drift clean; spec parity 93/93.
New script-arm unit suites in both languages (language selection, runtime:
pin, unknown pin, language mismatch, help and usage refusals without
executing, MIRAGE_CONFIG, stdin, crash, exit code, limit).
New e2e script CLIs: python on monty plus runtime: local and a yaml install
end to end (quickjs gated on MIRAGE_QUICKJS_HOME), typescript on monty and
quickjs, both covering $?, history recording and function shadowing.

Arguments and stdin are spelled per runtime (argv global on monty, sys.argv
on pyodide/wasi/local, scriptArgs on quickjs), which is the contract the
python3 and node commands already have; the CLI docs now state it in a
table. Snapshot capture for script installs and the worked examples follow in
the next PR.

- one frozen CLIInvocation per line; leaf handlers take fn(inv) - cli: resolves a name, module:ATTR, ./file.py:ATTR, or mirage.clis - CLISpec.script + runtime, from yaml script:/runtime: - script arm: runtime_for_language selects the interpreter, argv passes verbatim, config arrives as MIRAGE_CONFIG json, monty gains stdin

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

The snapshot test defines its own CLI leaf, which still took config as its first positional and so read the invocation record as the config.

zechengz · 2026-08-05T10:58:33Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 976c910a9e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…napshots - ScriptSource carries a module bit stamped from the extension at load, so a .mjs CLI reaches quickjs in ES-module mode - a path-form cli: ./tool.py:ATTR rebases on the config dir like script: - snapshots persist a script install by value (source, language, module, runtime pin) and load rebuilds the spec; a named install still travels by name - the tar manifest carries the clis key, which it omitted, so no install survived a disk snapshot - one cli_config_dump serves capture and copy, which crashed on a script install's mapping config

A grammarless script root now has its whole line forwarded and answers --help itself; declaring options opts back into mirage's parsing. A leaf that declares --help is handed the flag instead of being intercepted. The install config env is MIRAGE_CLI_CONFIG, since MIRAGE_CONFIG already names the workspace config file.

argv slot 0 carries the installed head word (RunArgs.prog), so a script CLI's own messages name it and two installs are distinguishable; monty, pyodide and quickjs fill it, while wasi and local keep CPython's -c. New integ/runtime/script_cli{,_js}.json drive the tier on both hosts and through the yaml -> daemon -> CLI path, which caught the daemon create route dropping the config's clis and guards options entirely.

An allowlist of StateKey entries silently dropped whatever it forgot from every tar snapshot while in-memory snapshots stayed green, which is how installed CLIs went missing. The manifest is now the state with only the four blob-bearing keys rewritten, plus a regression test that an unknown key survives the round trip.

eval_language duplicated Runtime.language, so a runtime could claim python at one door and js at the other; the disagreement only surfaced as an unexplained 127 or a policy evaluated on the wrong engine. The type is now a literal union, which made the two places that build a ScriptSource from an untyped string visible: the config loader is annotated, and the snapshot loader validates instead of trusting the file.

eslint's no-unnecessary-type-assertion fixer rewrote each `as AnyDict` on an indexed access into a non-null assertion, which no-non-null-assertion then refused, so the hook both modified the file and failed. Optional chaining satisfies both.

The engine asks for the mapping through one os call and mirage declined it, so a program reading os.environ ran on the python host and raised 'not supported in this environment' here. Returning the run env arrives in the guest as a dict, matching python's nine reads exactly; it is a copy, like OSAccess(environ=dict(environ)). No package upgrade needed, 0.0.19-beta.4 already emits the call. integ/runtime pins both spellings across hosts.

zechengz · 2026-08-05T23:45:53Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c28c1197e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

zechengz · 2026-08-06T00:52:31Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c28c1197e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

claude Bot reviewed Aug 5, 2026

View reviewed changes

test(cli): migrate the snapshot cli leaf to fn(inv)

976c910

The snapshot test defines its own CLI leaf, which still took config as its first positional and so read the invocation record as the config.

chatgpt-codex-connector Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread python/mirage/workspace/executor/command/cli.py Outdated

Comment thread python/mirage/config.py

Comment thread python/mirage/config.py

zechengz added 9 commits August 5, 2026 04:30

docs(cli): name both env spellings where the config is described

59b80ff

merge main: carry the git CLI verb doors on inv.ops

c28c119

chatgpt-codex-connector Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread python/mirage/workspace/snapshot/state.py

Comment thread python/mirage/workspace/executor/command/cli.py

Comment thread python/mirage/workspace/snapshot/state.py

chatgpt-codex-connector Bot reviewed Aug 6, 2026

View reviewed changes

Comment thread python/mirage/workspace/cli/registry.py

zechengz merged commit 9c2053b into main Aug 6, 2026
46 checks passed

zechengz deleted the feat/cli-invocation branch August 6, 2026 01:52

Navigation Menu

feat(cli): author a CLI in code, by pointer, or as a script - #712

feat(cli): author a CLI in code, by pointer, or as a script#712
zechengz merged 11 commits into
mainfrom
feat/cli-invocation

zechengz commented Aug 5, 2026

Uh oh!

claude Bot left a comment

Uh oh!

zechengz commented Aug 5, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zechengz commented Aug 5, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zechengz commented Aug 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

zechengz commented Aug 5, 2026

Summary

Test plan

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

zechengz commented Aug 5, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zechengz commented Aug 5, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zechengz commented Aug 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant