Refactor: Break up duct_main.py into smaller modules

[asmacdo]

Summary

Completes the module extraction from duct_main.py as outlined in #372.

Extracted modules:

• _formatter.py - SummaryFormatter class
• _signals.py - SigIntHandler
• _sampling.py - Platform-specific process sampling
• _output.py - TailPipe, output preparation, file cleanup
• _tracker.py - Report class and monitor_process function

Result:

• duct_main.py reduced from ~600 lines to ~180 lines
• Now contains only the execute() orchestration function and two constants

Deferred:

• Moving DUCT_OUTPUT_PREFIX and EXECUTION_SUMMARY_FORMAT to cli.py (requires refactoring ls.py parameter handling - tracked in Move CLI defaults to cli.py and refactor ls.py parameter handling #386)
• cli.py → _cli.py rename: This would have added a lot more, and might be better to just move to cli/
  Closes Refactor duct_main.py into smaller modules #372

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.12195% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.81%. Comparing base (c491bb4) to head (2bff9f5).
⚠️ Report is 22 commits behind head on main.

Files with missing lines	Patch %	Lines
src/con_duct/_signals.py	48.00%	13 Missing ⚠️
src/con_duct/_output.py	92.30%	4 Missing and 2 partials ⚠️
src/con_duct/_tracker.py	96.99%	2 Missing and 2 partials ⚠️
src/con_duct/_models.py	98.32%	2 Missing and 1 partial ⚠️
src/con_duct/_sampling.py	95.91%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #385      +/-   ##
==========================================
+ Coverage   91.38%   91.81%   +0.43%     
==========================================
  Files           8       15       +7     
  Lines        1056     1112      +56     
  Branches      138      138              
==========================================
+ Hits          965     1021      +56     
  Misses         69       69              
  Partials       22       22              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR successfully refactors duct_main.py by extracting code into smaller, focused modules as outlined in issue #372. The refactoring reduces duct_main.py from approximately 600 lines to 180 lines, improving maintainability and code organization.

Changes:

• Extracted 8 new private modules: _constants.py, _models.py, _utils.py, _formatter.py, _signals.py, _sampling.py, _output.py, and _tracker.py
• Updated imports across all source and test files to reference the new module structure
• Maintained DUCT_OUTPUT_PREFIX and EXECUTION_SUMMARY_FORMAT in duct_main.py as noted in the deferred work section

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/con_duct/_constants.py	New module containing __schema_version__, ENV_PREFIXES, and SUFFIXES constants
src/con_duct/_models.py	New module with data models (Enums: Outputs, RecordTypes, SessionMode; Dataclasses: SystemInfo, ProcessStats, LogPaths, Averages, Sample)
src/con_duct/_utils.py	New module with utility functions (assert_num, parse_version)
src/con_duct/_formatter.py	New module containing SummaryFormatter class for output formatting
src/con_duct/_signals.py	New module with SigIntHandler for signal handling
src/con_duct/_sampling.py	New module with platform-specific process sampling functions
src/con_duct/_output.py	New module with TailPipe class and I/O utility functions
src/con_duct/_tracker.py	New module containing Report class, monitor_process function, and __version__
src/con_duct/duct_main.py	Reduced to orchestration function execute() and two constants, imports from new modules
src/con_duct/cli.py	Updated imports to reference new module locations
src/con_duct/ls.py	Updated imports to reference new module locations
src/con_duct/json_utils.py	Updated imports to reference _constants module
src/con_duct/pprint_json.py	Updated imports to reference _formatter module
test/*.py	Updated all test imports to reference new module locations

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

'except' clause does nothing but pass and there is no explanatory comment.

Suggested change

	except Exception:
	except Exception:
	# Best-effort close: ignore errors (e.g., already closed or invalid objects).

[CodyCBakerPhD]

Well, this is the sort of thing that is not great (but we can fix in follow-up focusing on import control)

[asmacdo]

Yep I imagine constants should be public, but I figured for this approach, lets start off a bit ham-handed, and make everything private so we can be minimal as we transition to library usage.

[CodyCBakerPhD]

Testing helpers generally fall under a .testing public module

Can fix in follow up

[asmacdo]

this is used outside of tests also, but im open to move later.

[CodyCBakerPhD]

Basically, anything you import from the main package like this is a good example of something that should be publicly exposed either at root level or via some public submodule

Tests like this help indicate what might be intended to be exposed

[CodyCBakerPhD]

Overall LGTM - some discussion points for the importing specific followup above

@asmacdo I assume you have tried out this branch in practice (not just tests) and found it working to your liking?

Left my approval FWIW (have read-only permissions so doesn't mean much here)

[CodyCBakerPhD]

Keep in mind one of the great benefits of privatizing this kind of stuff (after fixing import structure in follow up) is after that you can feel free to alter the file/directory structure freely at will without worrying about breaking anything

[asmacdo]

I have tested locally, and it works. This isn't perfect, but I think it provides a nice structure to build on, so I'll merge after CI comes back green.