Repository navigation
docs: correct cli.md's microvm.toml section and envelope key lists against the code - #539
Merged
Merged
Conversation
…ainst the code The page said every microvm.toml key is a run flag (artifacts has none), that region takes any string (the loader refuses unlisted regions), and that every unusable file is ERR_CONFIG (conflicting egress keys are ERR_INVALID_ARG from run's merge). It also omitted two accepted keys, egress-posture as a reader, eight Response types rows, and keys the agent-up, agent-prompt, keepalive and dockerfile envelopes carry. Each claim was checked against the cited source at cae2ec7. mise run docs:check: EXIT=0.
10 of 11 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
docs/reference/cli.mdstates several things aboutmicrovm.tomland the success envelopes that the code at cae2ec7 contradicts or leaves out. This corrects them on that one page. No code changes.## Project config: microvm.tomlrunflag.artifactshas no flag spelling:crates/microvms-cli/src/config.rs:93-97("there is deliberately no flag spelling for a list this shape") andcrates/microvms-cli/src/commands/lifecycle.rs:406("Artifact globs have no flag spelling, so the file is their only source"). The sentence now names the exception.runanddoctorread the file.egress-posturedoes too: it flattensConfigFlags(crates/microvms-cli/src/cli.rs:1527-1546) and callsrun'smerge_config(crates/microvms-cli/src/commands/local.rs:880-885). The page's own shared-flag-groups list already named it as aConfigFlagscarrier.regiontakes "any region string". The loader refuses a region outside the listed set and names--unlisted-regionas the opt-in (crates/microvms-cli/src/config.rs:216-225). The comment now says so.egress-network-connectorsandshell(crates/microvms-cli/src/config.rs:72-81; merged atcrates/microvms-cli/src/commands/lifecycle.rs:288-298). They are added, the connector list commented out because it is refused beside the block'segress = true(lifecycle.rs:299-306). The example ARN is the one the docs already use elsewhere.-for_" now lists the four keys that differ from a flag name:binary,env,egress-network-connectorsandartifacts.ERR_CONFIG(exit 15). That holds for a file that fails to load (ConfigError,crates/microvms-cli/src/config.rs:118-130, mapped toExit::Configatlifecycle.rs:454-458). A file that loads but pairsegress = truewithdeny-egress = trueor withegress-network-connectorsis refused byrun's merge asERR_INVALID_ARG(exit 2) atlifecycle.rs:299-331. A new paragraph says so.### Response typesRESPONSE_TYPESanddocs/manifest.jsonboth list:wait,exists,adopt,names,image-versions,image-set-status,image-buildsandegress-posture. They are added inRESPONSE_TYPESorder with thetypeeach declares. Every row already present matched.crates/microvms-cli/src/commands/mod.rs:102-484stopped inside thelsrow; the table runs from the doc comment at line 103 to the closing];at line 553.Envelope key lists in the command sections
agent-up: the list lackedegressPosture, whichrenderinserts (crates/microvms-cli/src/commands/agent.rs:163). The added sentence says what it reports:openfor a VM the command launched, and on the refresh path the name record's posture, orunsealedwhen the record names none (posture_of,agent.rs:375-388; the default isEgressPosture::for_launch(false, false),crates/microvms-app/src/control/connector.rs:203-209and:279-282).agent-prompt: the list named eight keys.render_exec_as(crates/microvms-cli/src/commands/attached.rs:698-734) insertsexecId,phase,exitCode,stdout,stderr,truncated,outcome,signal,timedOut,posixExitCode,notesandsynthesized, andagent.rs:828-847addsagent,model,agentVersion,permissionMode,uid,executionTimeoutSecandreapGroupOnExit. The sentence now lists both groups.keepalive: the list lackedmicrovmId, the first keyattached.rs:846inserts.dockerfile: the envelope also carriesportandworkdir(crates/microvms-cli/src/commands/local.rs:1036-1041anddockerfile_rendered); the citedmod.rs:473-483was thelscomment block and now points at thedockerfilerow,mod.rs:542-552.What stays unverified
The findings came from a read-only audit of the page against the source. Every quoted range above was re-read with
sedat cae2ec7 before the edit, and the first and last line of each new citation are in the run's verify dump. No command was run against AWS. The page's other per-flag citations still carry pre-move line numbers and are not touched here.Evidence
mise run docs:checkon this branch: EXIT=0 in 84 s (baseline on main at cae2ec7 in the same worktree: EXIT=0 in 112 s).mise run pr-body:check -- --body <this body>: EXIT=0.transforminverify/guards/faults/*.tomlnamesdocs/reference/cli.md, soguards:listis unaffected.mise run checkwas not run: this changes one Markdown file underdocs/.Parity
microvms.pyi,index.d.ts).Guards
None: this adds no guard.
Follow-ups
RESPONSE_TYPESincrates/microvms-cli/src/commands/mod.rsomits keys the envelopes carry:outcome,signalandtimedOutforexec,ackandagent-prompt, andagentVersion,permissionMode,uid,executionTimeoutSecandreapGroupOnExitforagent-prompt, sodocs/manifest.json'sresponseKeyslacks them too.crates/microvms-cli/src/config.rsrepeat the claims fixed here: lines 6-7 (every knob is arunflag) and 66-68 (the loader refuses no region).quickstarthas no--configor--no-config, but it parses aruninvocation and callsrun(crates/microvms-cli/src/commands/lifecycle.rs:996-1022), whose merge loads./microvm.toml(lifecycle.rs:164-169). Whether quickstart should read a project file it gives no way to bypass is a design question; this page does not document it either way.Platform claims
Scope
(see
docs/STRATEGY.md).