Refactor core foundation (exceptions and bootstrap)

[jasonb5]

Description

• Adds CIME/core/exceptions.py with typed exception hierarchy extending CIMEError
• Adds CIME/core/config/bootstrap.py for centralized sys.path management
• Migrates internal CIMEError imports to use new location
• Adds 26 unit tests for exception hierarchy

Motivation

CIME's foundation has accumulated two recurring pain points that this PR addresses as the first slice of a broader CIME/core/ refactor:

Typed exceptions. Today there is a single CIMEError in CIME/utils.py, so callers can't distinguish a configuration problem from a build failure from a transient subprocess error without string-matching on messages. The new hierarchy (ConfigurationError, BuildError, SubmitError, SystemTestError, LockingError, ExternalCommandError, RetryableExternalCommandError, InputError) enables:

• Granular except clauses in callers (e.g. retry only transient subprocess errors)
• Clearer log and traceback context
• ExternalCommandError modeled on subprocess.CalledProcessError, carrying returncode, cmd, output, and stderr so run_cmd failures preserve diagnostic context

CIME.utils.CIMEError is re-exported from the new location so existing imports (internal or downstream) continue to work.

Centralized sys.path bootstrap. CIME is not pip-installed; every entry script (xmlchange, case.setup, create_newcase, etc.) does its own sys.path.insert to make import CIME... work. This duplicated logic has drifted in subtle ways. bootstrap_cime() provides:

• A single source of truth for path setup
• Three-way CIMEROOT resolution (explicit arg, env var, walk-up from __file__)
• Idempotent insertion (no duplicates, deterministic ordering)
• The Python version check previously in standard_script_setup.py

Existing call sites are intentionally unchanged in this PR — the module is standalone so subsequent slices can adopt it incrementally.

Why these two pieces first. They are dependency-free building blocks that the planned CIME/core/ DI-based abstractions (filesystem, process, env, clock) will rely on, so they need to land before the higher-level work.

Related

• Part of Refactor Slice 1: Foundation (typed exceptions, bootstrap, kill star imports) #4996 (Slice 1: Foundation — typed exceptions, bootstrap, kill star imports). This PR delivers the typed-exception hierarchy and the bootstrap module; the star-imports cleanup, GLOBAL removal, and conftest fix remain.
• Part of Refactor and API changes #4950 (refactor master tracker).

Checklist

• My code follows the style guidelines of this project (black formatting)
• I have performed a self-review of my own code
• My changes generate no new warnings
• I have added tests that exercise my feature/fix and existing tests continue to pass
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding additions and changes to the documentation

[github-actions]

You can preview documentation at https://esmci.github.io/cime/branch/feat/refactor-core-foundation/html/index.html

[jgfouca]

Looks good to me. Can you add motivation for this change in the description?

[billsacks]

I like the direction you're taking things here - thank you for this work! I have reviewed the production code and did a cursory look at the unit tests. I have a few comments. I appreciate the added testing here.

[billsacks]

Thank you for the fixes! See the comment I made about the algorithm for inserting paths, but as I note there, I'm fine with either approach. So I'm approving here and will let you decide which way to go.

[jasonb5]

Test failures are unrelated.