Repository navigation
refactor(cli): split cli.py into parser registrars and mirror owners - #20844
Conversation
Sensitive change review
|
Sensitive Change ReviewSensitive files changed:
|
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check that the one kept-line change, Not justified as shipped
What this change shipsInventory (9 items) — 8 justifiedIntent: keep
[FIRST-PRINCIPLES-REVIEWED] bc8edc9 Description read[DESCRIPTION-READ] cc016d9ff9b842ea80f724fbc8a2bde25981d8ba639795b8dcd7f72ce4f89b40 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] bc8edc9 Description read[DESCRIPTION-READ] b7f482416e0c78845c42dfb06303ad07d64508333a81229b40a2ad79e916eac1 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
571f929 to
6645984
Compare
Sensitive change review
|
6645984 to
25464a7
Compare
|
Rebased onto main 10b7fa7 and re-cut with the split recipe. This head supersedes the earlier head 6645984.
|
Sensitive change review
|
|
Sensitive change review
|
|
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved by a maintainer. The triage automation held this on a size, path or move-check rule only; every review lane is clean. Any lane note is accepted as follow-up work.
mbriones98
left a comment
There was a problem hiding this comment.
Checks green and readiness passed at 5cea02b; no behavior change.
cli.py was 3,862 lines and main() alone 2,502, past the 2,000-line cap. main() keeps the prologue, the top-level parser with the gateway command (pod's target_supports_flag reads its flags from cli.py) and the internal mcp-* servers, the boot steps and the dispatch chain. Every other command's arguments move verbatim into one register_<command>_parser per command in cli_parser_gateway/agent/admin, called in the same order. The jail gate, gateway-launch helpers, knowledge/consolidate handlers and the CLI logging move to cli_jail, cli_gateway_boot, cli_knowledge and cli_logging, owners of a kiro_crew._facade_mirror facade, so every name kiro_crew.cli held still resolves there and a patch through it reaches the module that reads it. The argparse tree main() builds is unchanged. Part of #20192
bc8edc9
5cea02b to
bc8edc9
Compare
Sensitive change review
|
|
|
Problem / Motivation
Goal: Bring
src/kiro_crew/cli.pyfrom 3,862 lines to 1,114, under the 2,000-line cap, with thekirocrewcommand line behaving exactly as before.cli.pyis the entry point for everykirocrewcommand and one of the most-edited files in the tree (18 commits in the last 7 days). Itsmain()alone was 2,502 lines: about 1,950 of argparse definitions, then the boot steps and the dispatch chain. That is past the repository's 2,000-line rule, so every change to a command's arguments meant editing one giant function.Part of #20192
Why it matters
A file this size can't follow the code-style rule (no hand-written file over 2,000 lines), and the next command added to it pushes it further over. With the parser split by help section and the helpers in modules of their own, a new command's arguments go into a small registrar module, and
cli.pykeeps only the entry point. Its CI baseline row for the line cap goes away.Not a goal
workspace --dirhelp strings (they still say "KiroCrew data home"). That is a user-visible text change and belongs in its own PR.cli_commands.py,cli_server.pyorcli_doctor.py, or any test file.main()dispatches, or the order of its boot steps.What changed (motivation → approach → change)
main()was one function holding three jobs: build the argparse tree, run the boot steps, dispatch. The boot steps and the dispatch chain are pinned tomainby tests and by the token-mint guard (security/inline_payload._MINT_SURFACE_REnameskiro_crew.cliand none of the newcli_*modules), and thegatewaycommand's own flags are read fromcli.py's text bypod.runtime_boot.target_supports_flag. So those stay. What moves is everything a reader never needs in the entry point:cli_parser_gateway.pygatewaycli_parser_agent.pycli_parser_admin.pycli_logging.pygateway.loglogging, the log-queue listener and its drainscli_jail.pycli_gateway_boot.pygatewaybranch prepares beforeasyncio.runcli_knowledge.pyknowledgeandconsolidatehandlersEach registrar is one
register_<command>_parser(sub)holding that command's base block verbatim;main()calls them in the base registration order (perf,benchanddesktopkeep their own modules' registrars). The four helper modules are owners of akiro_crew._facade_mirrorfacade, so every namecli.pyhad still resolves onkiro_crew.clias the same object, and amonkeypatch/mock.patchthroughkiro_crew.clireaches the module that reads the name.cli.pykeeps binding every project name it imported before (# noqa: F401where only an owner reads it now). The registrars are plain modules: they read no name a test patches through the facade, and a test pins that.Registries follow the moved code:
.github/file-line-cap-baseline.txtlosescli.py's row; the boot-path rule inAUTOSDE.yamlalso covers the four owners andcli_parser_*.py, all imported onimport kiro_crew.cli(path globs only); andsrc/kiro_crew/security_posture.pylistscli_logging.pyinstead ofcli.pyas the non-egress module that installs log redaction. The owning spec (docs/system-specs/modules/cli.md) gains a module-layout section, and seven spec sentences in six files that namedcli.pyas the home of moved code now name the new module.Backwards compatibility
Compatible: every name
kiro_crew.clibound before still resolves there as the same object (test/campaign_facade_inventories/kiro_crew.cli.json, 46 names, checked bytest/test_campaign_facades_base_public_names.py); the console script,python -m kiro_crewand every import path are unchanged.Reader: src/kiro_crew/platform_compat.py:exit_after_failed_restart_exec -- chat -- imports
drain_log_queue_before_hard_exitfromkiro_crew.cliat call time; the facade serves thecli_loggingfunction (test_restart_pruned_interpreter_guard.py, test_gateway_exit_path.py)Reader: src/kiro_crew/slack/events.py:_handle_restart -- chat -- same lazy
from kiro_crew.cli import drain_log_queue_before_hard_exit, same object (test_gateway_exit_path.py)Reader: src/kiro_crew/slack/gateway_runtime/exit_path.py:_shutdown_and_exit -- chat -- same lazy import, same object; its
_stop_log_queue_listenerimport is served the same way (test_gateway_exit_path.py, test_restart_waits_for_cut_turns.py)Move audit
move_audit.pycountsmainas one unit. The supplementary per-statement audit finds all 519 top-level statements of the basemainAST-identical at HEAD (462 in the registrar modules, 57 still incli.py), somainchanged only by losing them and gaining the registrar calls. The only other changed unit,_fd_targets_file, rewords one docstring line ("Used to detect" -> "Detects") for the comment-history gate. One kept line changes: the facade'slogger = logging.getLogger(__name__)becomeslogging.getLogger("kiro_crew.cli")— the same object under a normal import, and the one the owners bind, so the mirror's one-object-per-name install also holds when the file runs as__main__(python -m kiro_crew.cli, which at base ran the body and exited 0;test_the_facade_installs_when_it_runs_as_mainpins it). Comment-only edits in moved code: 21 leading comments that only repeated the command name are dropped (the registrar's name says it), the base's misplaced# policy — governance model inspectioncomment moves from abovetailnetto abovepolicy, the cloud block's comment spells "Kiro Crew", and three moved comments that pointed at text left behind incli.mainnow say where it is (--no-jailcomment "above" -> "in cli.main"; the deferreddashboard.urlsimport's "cli.py's module scope" -> "the module scopeimport kiro_crew.cliloads"). The twoworkspace --dirhelp strings keep their base text and carry# brand-ok(help text is behaviour).Behaviour proof: the full argparse tree
main()builds — every subparser'sformat_help(), every action's option strings, dest, default, type, choices, help and metavar, argument and mutually-exclusive groups, and the order of the subcommand map — dumps byte-identical at base and HEAD.Changes main made to the moved code while this PR was open moved the same way and are in the dumps and audit above:
cli.mainkas)kasparser block and its dispatch branchcli_parser_gateway.register_kas_parser, called afterregister_sandbox_parser; the dispatch branch stays inmainspawn run --agent/--crew)spawn_run.add_argumentcallscli_parser_agent.register_spawn_parser_consolidate_cmd's refused-pass messagecli_knowledge._consolidate_cmdThis head was pushed onto the branch from outside the campaign's push queue. Running the split recipe on current main produces the same commit, byte for byte in
cli.pyandcli_parser_agent.pyand hunk for hunk in every file, so it is the head that was reviewed. TheGoalline's figures were measured at this PR's first base; at this headcli.pygoes from 3,902 lines to 1,121.Diff alignment:
git diffandgit diff --minimaladd the same lines in every changed file exceptcli.py, where the default diff adds 202 lines and--minimal124. The 78 extra lines are unchanged code that stays incli.py, shown by git's default (heuristic) diff as removed and added again: thesub = parser.add_subparsers(...)call, thegatewayparser block, and theregister_perf_parser/register_bench_parser/register_desktop_parsercalls. No blank-line or comment layout ofcli.pylines the two up at this base (every single and paired layout toggle inmain's parser region was tried), and the added-line gates that read the default diff pass on these lines.Tests
test/test_cli_split_facade.py(new): the patch scan reads every spelling tests use and nothing else; it finds 14 known seams (non-vacuity); every scanned name is routed to every owner holding it, with a blinded-index self-test; a patch of each scanned name through the facade reaches every holder; owners, no exclusion, no forwards; no owner or registrar imports the facade or an owner; served names from outside the family stay visible to type checkers, and every base public name type-checks through the facade (with a self-test); owners log askiro_crew.cli; the log-queue slot lives incli_loggingand a facade write lands there; registrars read no patched name (with a self-test);maincalls every registrar exactly once, beforehide_internal_commands; the facade installs when the file runs as__main__; andscripts/leaf_test_scope.corpus_gatesderives the file as a corpus gate, since it reads the whole test tree.test/test_cli_split_dispatch.py(new): runs the realmainfor every command butgateway(test_cli.py's lock-refusal and--seedtests drive that branch in-process), with the boot steps and the handler as recorders, and pins which handler each command reaches and with what, the prologue's order, theKIROCREW_PORTrefusals and the bare-kirocrewbanner. These branches were exercised only by subprocess tests, which coverage does not see.test/test_cli_gateway_boot.py(new): the lock-refusal port and bind-address diagnostics, the configured port read through acli.KiroCrewConfigpatch. It is a separate 69-line file because these are thecli_gateway_bootowner's own coverage-floor tests, under thetest_cli_<module>.pyconvention.test_pod.py(pod--approvalchoices,pod_*names),test_packaged_docs_runtime_facts_b78.py,test_denied_commands_security.py,test_file_delivery_consent.py,test_internal_python_isolation.py,test_platform_cpp_seam_coverage.py,test_spawn_audit.py(BENIGN row),test_cli_lazy_imports.py(its function-local import scan walkscli.mainjoined with thecli_parser_*registrar functions, so thekasblock'scli_kasimport keeps its case: the same 50 node ids as on main), and the negative pinstest_aws_consent.py,test_owner_only_files.py,test_cli.py::TestBannerBrandingnow scancli.pyjoined with every split-out module. Comments in those files that namedcli.pyas the home of a moved construct now name the new one (two in test_pod.py, one in test_platform_cpp_seam_coverage.py, one docstring in test_denied_commands_security.py); no assertion changed.kiro_crew.clior a split-out module, thekasandspawn run --agent/--crewtests, plus the facade, line-cap, encoding and flake guards): 11052 passed, 18 skipped, 0 failed; mypy oversrc/kiro_crewclean.scripts/local-gate.py --dry-runselects 2144 backend and 648 frontend files, so the floor is the targeted run and CI runs the full matrix. New tests: 5 runs at-n0and one at-n 3(92 passed), all green; no sleep, clock or port in them.src/kiro_crew), comment history, brand, harness parity, subprocess encoding, agent-sdk boundary, sync-io-in-async (with a planted-call proof that it scans both moved coroutines), memory-store seam, file line cap, docs lint, feature map, semgrep (CI command, 0 findings).CI path references
No workflow file changes.
AUTOSDE.yamlruleno-new-work-on-gateway-boot-path(blocking) namedsrc/kiro_crew/cli.py; it now also namessrc/kiro_crew/cli_gateway_boot.py,src/kiro_crew/cli_jail.py,src/kiro_crew/cli_knowledge.py,src/kiro_crew/cli_logging.pyandsrc/kiro_crew/cli_parser_*.py. All of them are imported at module scope byimport kiro_crew.cli, which the gateway runs beforeasyncio.run, so the code that leftcli.pystays under the rule that covered it there. Path globs only; the rule text is unchanged.Prose citations (L29)
Comments and docstrings that named
cli.pyas the home of a moved construct; only the cited path changed:test/test_pod.py:8029cli.py->cli_parser_admin.py(the pod--approvalchoices);:8049cli.py repeats the choices literal->cli_parser_admin.py repeats ...test/test_platform_cpp_seam_coverage.py:107cli.py->cli_jail.py(thectx.jailtwo-step)test/test_denied_commands_security.py:565-568docstring:cli.py builds its parser inline in main()->cli.main() builds its parser inline from the cli_parser_* registrarssrc/kiro_crew/acp/runtime.py:772(see cli.py)->(see cli_logging.py)(the RotatingFileHandler)src/kiro_crew/history_index_worker.py:97(see cli.py and session_lifecycle.py)->(see cli_logging.py and session_lifecycle.py)(theos._exitdrain)src/kiro_crew/memory.py:251,test/test_memory_stores.py:542cli.pytakes the first->cli_knowledge.pytakes the first(MemoryStore()in_consolidate_cmd)test/test_consolidate_cmd.py:25paths in cli.py->paths in cli_knowledge.pysrc/kiro_crew/pod/runtime.py:188The top-level ``cli.py`` repeats the literal->The top-level ``cli_parser_admin.py`` repeats the literalsrc/kiro_crew/acp/client_lifecycle.py:108(see cli.py)->(see cli_logging.py)(the RotatingFileHandler)src/kiro_crew/acp/client_lifecycle.py:167(session_allocation.py calls->(session_allocation_parts/get_or_create.py calls(whereprovider.client.rekeyis called, asacp/session_provider.pyalready says)Manual verification
N/A — unit coverage sufficient: the change moves code without changing it, and the argparse-tree dump plus the per-statement audit prove that directly.
Related Issues
Part of #20192
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).