python-cli-output-side-effect

Answer

Root cause (gen-compose.py): the config-write block (write_config_file → compose/generated/<name>/config/config.yaml) executed unconditionally in main(), before the --output branch. So even when the user passed --output PATH or --output -, the tool dirtied the repository — and worse, it created the compose/generated/<name> directory tree itself.

Fix: gate the config write (and the entire repo-write path) into the default-mode branch only. Explicit --output PATH and stdout (-) now return early with zero writes under compose/generated/ — not even the directory:

# gen-compose.py, main() tail (fixed)
# --- render the compose document once; all modes reuse it -------------
compose_text = render_compose(config)
name = config["name"]
paths = compose_artifact_paths(name)

# ---- route the rendered document --------------------------------------
# --output PATH  -> write ONLY the compose YAML to PATH; zero repo writes
# --output -     -> write the compose YAML to stdout; zero repo writes
# default        -> persist the full bundle under compose/generated/<name>/
#                   (config/config.yaml + docker-compose.yml).  This is the
#                   ONLY branch that is allowed to touch the repository.
if args.output and args.output != "-":
    target = Path(args.output)
    if args.dry_run:
        print(f"{PROG}: would write compose: {target}")
    else:
        write_compose_file(compose_text, target)
        if not args.quiet:
            print(f"{PROG}: wrote compose: {target}")
    return 0

if args.output == "-":
    if not args.dry_run:
        sys.stdout.write(compose_text)
    return 0

# default mode -- the only branch that writes into the repository
if args.dry_run:
    print(f"{PROG}: would write config: {paths['config_file']}")
    print(f"{PROG}: would write compose: {paths['compose_file']}")
else:
    write_config_file(config, paths["config_file"])
    write_compose_file(compose_text, paths["compose_file"])
    if not args.quiet:
        print(f"{PROG}: wrote config: {paths['config_file']}")
        print(f"{PROG}: wrote compose: {paths['compose_file']}")

return 0

Because the repo write happens only in the else default branch, no compose/ directory is ever created for the --output modes (paths are anchored to Path.cwd() and only touched by write_config_file/write_compose_file inside that branch). --dry-run semantics are preserved for all three modes. The original write_default_bundle helper (dead code after the refactor) was removed.

Tests (test_gen_compose.py, 3 new regression tests marked NEW): 1. test_stdin_output_path_leaves_no_repo_dir — the exact acceptance: --stdin --output <tmp>/out.yml then assert compose/generated/probe (and the whole compose/ tree) does not exist, target file contains valid compose. 2. test_output_stdout_produces_zero_repo_writes — --output - writes only to stdout (no "wrote" status lines, no repo dir), and stdout parses as compose with the expected service. 3. test_output_path_with_custom_name_writes_only_target — --name widget --output <tmp>/custom/out.yaml creates only the target file (parents created for it) and leaves the repo side completely untouched.

Existing behavior tests retained: default-mode bundle + config roundtrip, --dry-run writes nothing, spec-file input.