netcanon 0.1.0__tar.gz

netcanon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Netcanon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netcanon-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: netcanon
+Version: 0.1.0
+Summary: Multi-vendor network config translator with a verifiable cross-vendor audit
+Author: Netcanon contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/netcanon/netcanon
+Project-URL: Repository, https://github.com/netcanon/netcanon
+Project-URL: Issues, https://github.com/netcanon/netcanon/issues
+Project-URL: Changelog, https://github.com/netcanon/netcanon/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/netcanon/netcanon/blob/main/README.md
+Keywords: network-automation,network-configuration,cisco,juniper,fortinet,aruba,mikrotik,opnsense,arista,vendor-translation,config-migration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: netmiko>=4.4.0
+Requires-Dist: paramiko>=3.4.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: apscheduler>=3.10.4
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: keyring>=24.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-playwright>=0.5.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
+Requires-Dist: coverage>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Provides-Extra: desktop
+Requires-Dist: PySide6>=6.7.0; extra == "desktop"
+Requires-Dist: pystray>=0.19.0; extra == "desktop"
+Requires-Dist: Pillow>=10.0.0; extra == "desktop"
+Provides-Extra: desktop-build
+Requires-Dist: netcanon[desktop]; extra == "desktop-build"
+Requires-Dist: cx_Freeze>=7.0.0; extra == "desktop-build"
+Dynamic: license-file
+
+# Netcanon
+
+**Multi-vendor network config translator with a verifiable cross-vendor audit.**
+
+Translates running-config between Cisco IOS-XE, Juniper Junos, Aruba
+AOS-S, Arista EOS, FortiGate, MikroTik RouterOS, and OPNsense.
+Per-field capability declarations and a cross-mesh audit catch silent
+translation errors before they ship.  Explicit Tier-3 boundary on
+firewall / NAT / VPN / QoS — see
+[`docs/CAPABILITIES.md`](docs/CAPABILITIES.md).  See also
+[`docs/COMPARISON.md`](docs/COMPARISON.md) for positioning vs Batfish /
+Capirca / NAPALM and the rest of the network-automation landscape.
+
+Two concerns, one FastAPI application:
+
+1. **Backup** — pull `running-config` (or vendor equivalent) from network
+   devices over SSH / NETCONF / REST, store verbatim in
+   `configs/<hostname>.<ext>`.  Runs on a schedule or on demand.
+2. **Migration** — translate a stored backup from one vendor's config
+   grammar to another through a shared canonical intent tree.  Cisco
+   IOS-XE → Aruba AOS-S, FortiGate → OPNsense, etc.
+
+Ships on two platforms kept at strict feature parity:
+
+| Platform | Package | Entry point |
+|---|---|---|
+| Web (browser) | `netcanon/` | `uvicorn netcanon.main:app` |
+| Desktop (Windows) | `netcanon_desktop/` | `python -m netcanon_desktop` |
+
+---
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+uvicorn netcanon.main:app --host 127.0.0.1 --port 8000
+# -> http://127.0.0.1:8000        (UI)
+# -> http://127.0.0.1:8000/docs   (Swagger)
+```
+
+Desktop shell:
+
+```bash
+pip install -e ".[desktop]"
+python -m netcanon_desktop
+```
+
+Run the test suite:
+
+```bash
+pytest                       # unit + integration + desktop (fast)
+pytest -m e2e                # Playwright browser tests (slower)
+```
+
+Tests run across four layers: unit (pure functions, no I/O — the
+real-capture validation harness lives here as a unit subset),
+integration (TestClient + mocked SSH), e2e (Playwright against a
+live Uvicorn), and desktop (PySide6 + pystray mocked).  CI output
+is the source of truth for pass counts.
+
+---
+
+## Where to go next
+
+| You want to… | Start here |
+|---|---|
+| Understand the architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) — four-layer model, canonical bridge, codec types |
+| Follow the contributor rules | [`CLAUDE.md`](CLAUDE.md) — hard rules, parity checklist, gotchas |
+| Look up project jargon | [`docs/glossary.md`](docs/glossary.md) — canonical, codec, mesh, ship-before-wire, target profile, etc. |
+| Read the canonical model overview | [`netcanon/migration/canonical/README.md`](netcanon/migration/canonical/README.md) — Tier 1 / 2 / 3 fields and promotion rules |
+| Add or change an HTTP route | [`netcanon/api/routes/README.md`](netcanon/api/routes/README.md) — frozen pipeline-stage signatures, endpoint inventory |
+| Add a new codec (vendor parser/renderer) | [`netcanon/migration/codecs/README.md`](netcanon/migration/codecs/README.md) |
+| Add a new device definition / target profile | [`definitions/README.md`](definitions/README.md) — layered definitions (family base + os_version / model overlays), target-profile module-variant schema |
+| Add a new canonical field | [`docs/adding-a-canonical-field.md`](docs/adding-a-canonical-field.md) — MTU as a worked example |
+| Add a new target-profile YAML | [`docs/adding-a-target-profile.md`](docs/adding-a-target-profile.md) — flat-port + module-variant shapes, fit-check propagation |
+| Ship a feature across web + desktop | [`docs/feature-parity-walkthrough.md`](docs/feature-parity-walkthrough.md) — SNMPv3 USM rename as a worked example |
+| See what's shipped recently / current state | [`CHANGELOG.md`](CHANGELOG.md) — authoritative per-wave shipping log |
+| Read the slower-changing architectural sketch | [`translator-plans.txt`](translator-plans.txt) — dense, grep-friendly long-term roadmap; most R / GAP / Phase items now `[SHIPPED]` |
+| Check codec certification tiers | [`tests/fixtures/real/RESULTS.md`](tests/fixtures/real/RESULTS.md) |
+| Manually exercise recent changes | [`HUMAN_TESTING.md`](HUMAN_TESTING.md) |
+| Write tests | [`tests/README.md`](tests/README.md) |
+| Review the security model | [`SECURITY.md`](SECURITY.md) — threat model, controls, known limitations |
+| Look up what Netcanon translates and what it doesn't | [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) — operator-facing capabilities, per-codec unsupported/lossy paths, Tier-3 boundary, notification surfaces |
+
+---
+
+## Layout
+
+```
+netcanon/              FastAPI application (shared by both platforms)
+ ├── api/routes/          HTTP endpoints (backups, migration, configs, …)
+ ├── collectors/          SSH/NETCONF/REST fetchers — one factory,
+ │                        one mock-point (`get_collector`)
+ ├── migration/           Cross-vendor translation pipeline
+ │   ├── canonical/         CanonicalIntent model + shared transforms
+ │   ├── codecs/            Per-vendor parse/render implementations
+ │   └── ...
+ ├── services/            Plain-function orchestrators (pipeline, detect, …)
+ ├── storage/             FileConfigStore
+ └── templates/           Jinja2 templates (every interactive element
+                          must carry a data-testid — see CLAUDE.md)
+
+netcanon_desktop/      Windows tray/webview shell around the same server
+definitions/            Device definition YAMLs (shared with backup layer)
+tests/unit/             Pure-function tests, no I/O
+tests/integration/      FastAPI TestClient tests, SSH mocked at get_collector
+tests/e2e/              Playwright browser tests against a live Uvicorn
+tests/desktop/          PySide6/pystray-mocked desktop shell tests
+tests/fixtures/real/    Real-capture validation corpus (see RESULTS.md)
+scripts/                One-off utilities (Aruba template renderer, …)
+```
+
+---
+
+## Certification status
+
+Per-codec certainty (read from `CanonicalCodec.certainty` at module load,
+surfaced via `GET /api/v1/migration/adapters`).  See
+[`tests/fixtures/real/RESULTS.md`](tests/fixtures/real/RESULTS.md) for
+the live per-codec status — RESULTS.md is the source of truth and this
+README intentionally omits per-codec counts to avoid drift.
+
+---
+
+## License
+
+See [`SECURITY.md`](SECURITY.md) for responsible-disclosure policy.
+Project licence is per-file (most files are MIT; third-party fixtures
+keep their upstream licences — see
+[`tests/fixtures/real/NOTICE.md`](tests/fixtures/real/NOTICE.md)).

netcanon-0.1.0/README.md

@@ -0,0 +1,130 @@
+# Netcanon
+
+**Multi-vendor network config translator with a verifiable cross-vendor audit.**
+
+Translates running-config between Cisco IOS-XE, Juniper Junos, Aruba
+AOS-S, Arista EOS, FortiGate, MikroTik RouterOS, and OPNsense.
+Per-field capability declarations and a cross-mesh audit catch silent
+translation errors before they ship.  Explicit Tier-3 boundary on
+firewall / NAT / VPN / QoS — see
+[`docs/CAPABILITIES.md`](docs/CAPABILITIES.md).  See also
+[`docs/COMPARISON.md`](docs/COMPARISON.md) for positioning vs Batfish /
+Capirca / NAPALM and the rest of the network-automation landscape.
+
+Two concerns, one FastAPI application:
+
+1. **Backup** — pull `running-config` (or vendor equivalent) from network
+   devices over SSH / NETCONF / REST, store verbatim in
+   `configs/<hostname>.<ext>`.  Runs on a schedule or on demand.
+2. **Migration** — translate a stored backup from one vendor's config
+   grammar to another through a shared canonical intent tree.  Cisco
+   IOS-XE → Aruba AOS-S, FortiGate → OPNsense, etc.
+
+Ships on two platforms kept at strict feature parity:
+
+| Platform | Package | Entry point |
+|---|---|---|
+| Web (browser) | `netcanon/` | `uvicorn netcanon.main:app` |
+| Desktop (Windows) | `netcanon_desktop/` | `python -m netcanon_desktop` |
+
+---
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+uvicorn netcanon.main:app --host 127.0.0.1 --port 8000
+# -> http://127.0.0.1:8000        (UI)
+# -> http://127.0.0.1:8000/docs   (Swagger)
+```
+
+Desktop shell:
+
+```bash
+pip install -e ".[desktop]"
+python -m netcanon_desktop
+```
+
+Run the test suite:
+
+```bash
+pytest                       # unit + integration + desktop (fast)
+pytest -m e2e                # Playwright browser tests (slower)
+```
+
+Tests run across four layers: unit (pure functions, no I/O — the
+real-capture validation harness lives here as a unit subset),
+integration (TestClient + mocked SSH), e2e (Playwright against a
+live Uvicorn), and desktop (PySide6 + pystray mocked).  CI output
+is the source of truth for pass counts.
+
+---
+
+## Where to go next
+
+| You want to… | Start here |
+|---|---|
+| Understand the architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) — four-layer model, canonical bridge, codec types |
+| Follow the contributor rules | [`CLAUDE.md`](CLAUDE.md) — hard rules, parity checklist, gotchas |
+| Look up project jargon | [`docs/glossary.md`](docs/glossary.md) — canonical, codec, mesh, ship-before-wire, target profile, etc. |
+| Read the canonical model overview | [`netcanon/migration/canonical/README.md`](netcanon/migration/canonical/README.md) — Tier 1 / 2 / 3 fields and promotion rules |
+| Add or change an HTTP route | [`netcanon/api/routes/README.md`](netcanon/api/routes/README.md) — frozen pipeline-stage signatures, endpoint inventory |
+| Add a new codec (vendor parser/renderer) | [`netcanon/migration/codecs/README.md`](netcanon/migration/codecs/README.md) |
+| Add a new device definition / target profile | [`definitions/README.md`](definitions/README.md) — layered definitions (family base + os_version / model overlays), target-profile module-variant schema |
+| Add a new canonical field | [`docs/adding-a-canonical-field.md`](docs/adding-a-canonical-field.md) — MTU as a worked example |
+| Add a new target-profile YAML | [`docs/adding-a-target-profile.md`](docs/adding-a-target-profile.md) — flat-port + module-variant shapes, fit-check propagation |
+| Ship a feature across web + desktop | [`docs/feature-parity-walkthrough.md`](docs/feature-parity-walkthrough.md) — SNMPv3 USM rename as a worked example |
+| See what's shipped recently / current state | [`CHANGELOG.md`](CHANGELOG.md) — authoritative per-wave shipping log |
+| Read the slower-changing architectural sketch | [`translator-plans.txt`](translator-plans.txt) — dense, grep-friendly long-term roadmap; most R / GAP / Phase items now `[SHIPPED]` |
+| Check codec certification tiers | [`tests/fixtures/real/RESULTS.md`](tests/fixtures/real/RESULTS.md) |
+| Manually exercise recent changes | [`HUMAN_TESTING.md`](HUMAN_TESTING.md) |
+| Write tests | [`tests/README.md`](tests/README.md) |
+| Review the security model | [`SECURITY.md`](SECURITY.md) — threat model, controls, known limitations |
+| Look up what Netcanon translates and what it doesn't | [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) — operator-facing capabilities, per-codec unsupported/lossy paths, Tier-3 boundary, notification surfaces |
+
+---
+
+## Layout
+
+```
+netcanon/              FastAPI application (shared by both platforms)
+ ├── api/routes/          HTTP endpoints (backups, migration, configs, …)
+ ├── collectors/          SSH/NETCONF/REST fetchers — one factory,
+ │                        one mock-point (`get_collector`)
+ ├── migration/           Cross-vendor translation pipeline
+ │   ├── canonical/         CanonicalIntent model + shared transforms
+ │   ├── codecs/            Per-vendor parse/render implementations
+ │   └── ...
+ ├── services/            Plain-function orchestrators (pipeline, detect, …)
+ ├── storage/             FileConfigStore
+ └── templates/           Jinja2 templates (every interactive element
+                          must carry a data-testid — see CLAUDE.md)
+
+netcanon_desktop/      Windows tray/webview shell around the same server
+definitions/            Device definition YAMLs (shared with backup layer)
+tests/unit/             Pure-function tests, no I/O
+tests/integration/      FastAPI TestClient tests, SSH mocked at get_collector
+tests/e2e/              Playwright browser tests against a live Uvicorn
+tests/desktop/          PySide6/pystray-mocked desktop shell tests
+tests/fixtures/real/    Real-capture validation corpus (see RESULTS.md)
+scripts/                One-off utilities (Aruba template renderer, …)
+```
+
+---
+
+## Certification status
+
+Per-codec certainty (read from `CanonicalCodec.certainty` at module load,
+surfaced via `GET /api/v1/migration/adapters`).  See
+[`tests/fixtures/real/RESULTS.md`](tests/fixtures/real/RESULTS.md) for
+the live per-codec status — RESULTS.md is the source of truth and this
+README intentionally omits per-codec counts to avoid drift.
+
+---
+
+## License
+
+See [`SECURITY.md`](SECURITY.md) for responsible-disclosure policy.
+Project licence is per-file (most files are MIT; third-party fixtures
+keep their upstream licences — see
+[`tests/fixtures/real/NOTICE.md`](tests/fixtures/real/NOTICE.md)).

netcanon-0.1.0/netcanon/__init__.py

@@ -0,0 +1,23 @@
+"""
+netcanon — multi-vendor network configuration backup and translation engine.
+
+Package layout
+--------------
+netcanon.config          Application settings (env-var driven via pydantic-settings).
+netcanon.models          Domain models: DeviceTarget, BackupJob, ConfigRecord, etc.
+netcanon.definitions     YAML definition loader and Pydantic schema.
+netcanon.storage         Pluggable config storage (file-based v1).
+netcanon.collectors      SSH collection strategies (Netmiko, Paramiko shell).
+netcanon.api             FastAPI router modules.
+netcanon.main            Application factory (create_app).
+
+Entry point
+-----------
+Run the server:
+    uvicorn netcanon.main:app --reload
+
+Or programmatically (e.g. in tests):
+    from netcanon.main import create_app
+    from netcanon.config import Settings
+    app = create_app(Settings(configs_dir=tmp_path))
+"""

netcanon-0.1.0/netcanon/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI router modules for the Netcanon REST API."""

netcanon-0.1.0/netcanon/api/deps.py

@@ -0,0 +1,84 @@
+"""
+FastAPI dependency providers.
+
+These functions are injected via ``Depends()`` into route handlers so
+that handlers never reference ``app.state`` directly.  Indirection makes
+unit testing easier: swap the dependency override instead of patching
+``app.state``.
+
+Usage::
+
+    @router.get("/definitions")
+    def list_defs(definitions: Definitions = Depends(get_definitions)):
+        ...
+"""
+
+from typing import TYPE_CHECKING
+
+from fastapi import Request
+
+from ..definitions.loader import DefinitionLoader
+from ..definitions.schema import DeviceDefinition
+from ..models.backup import BackupJob
+from ..models.device_profile import DeviceProfile
+from ..models.schedule import BackupSchedule
+from ..storage.base import BaseConfigStore
+from ..storage.device_profile_store import FileDeviceProfileStore
+from ..storage.job_store import FileJobStore
+from ..storage.schedule_store import FileScheduleStore
+
+if TYPE_CHECKING:
+    pass
+
+
+def get_definitions(request: Request) -> dict[str, DeviceDefinition]:
+    """Inject the loaded device-definition registry from application state."""
+    return request.app.state.definitions
+
+
+def get_definition_loader(request: Request) -> DefinitionLoader:
+    """Inject the DefinitionLoader instance so backup routes can call
+    :meth:`DefinitionLoader.resolve` for overlay lookup.  The dict
+    returned by :func:`get_definitions` stays as the family-base
+    registry for endpoints that iterate type_keys."""
+    return request.app.state.definition_loader
+
+
+def get_storage(request: Request) -> BaseConfigStore:
+    """Inject the config storage backend from application state."""
+    return request.app.state.storage
+
+
+def get_jobs(request: Request) -> dict[str, BackupJob]:
+    """Inject the in-memory backup-job registry from application state."""
+    return request.app.state.jobs
+
+
+def get_job_store(request: Request) -> FileJobStore:
+    """Inject the job persistence store from application state."""
+    return request.app.state.job_store
+
+
+def get_schedules(request: Request) -> dict[str, BackupSchedule]:
+    """Inject the in-memory schedule registry from application state."""
+    return request.app.state.schedules
+
+
+def get_schedule_store(request: Request) -> FileScheduleStore:
+    """Inject the schedule persistence store from application state."""
+    return request.app.state.schedule_store
+
+
+def get_scheduler(request: Request):
+    """Inject the APScheduler instance from application state."""
+    return request.app.state.scheduler
+
+
+def get_device_profiles(request: Request) -> dict[str, DeviceProfile]:
+    """Inject the in-memory device profile registry from application state."""
+    return request.app.state.device_profiles
+
+
+def get_device_profile_store(request: Request) -> FileDeviceProfileStore:
+    """Inject the device profile persistence store from application state."""
+    return request.app.state.device_profile_store

netcanon-0.1.0/netcanon/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API route modules — imported and included by the application factory."""

netcanon-0.1.0/netcanon/api/routes/_migration_helpers.py

@@ -0,0 +1,183 @@
+"""
+Helpers extracted from :mod:`netcanon.api.routes.migration` for the
+``refactor/god-file-cleanup`` branch.
+
+Public surface:
+
+* :func:`resolve_adapter_or_422` — translate adapter-name lookup
+  errors into 422s with side-aware ``source`` / ``target`` framing.
+* :func:`resolve_input_text` — return the raw config text referenced
+  by a :class:`MigrationPlanRequest` body, enforcing the
+  ``raw_text`` XOR ``source_filename`` invariant and translating
+  storage misses into 404s.
+* :func:`get_target_profiles` — pull the target-profile registry
+  from ``request.app.state``; returns an empty dict when the
+  attribute is absent (some unit-test fixtures don't run the full
+  lifespan).
+* :func:`build_codec_info_list` — shape the registered codec list
+  into :class:`CodecInfo` records for ``GET /adapters``, joining
+  each codec's :class:`CapabilityMatrix` with the corresponding
+  vendor's ``display_name``.
+* :func:`request_has_overrides_or_profile` — boolean predicate that
+  decides whether ``POST /plan`` should route through the
+  rename-aware :func:`run_plan_with_overrides` (any per-category
+  map present, or a target profile selected).
+
+Routes orchestrate; these helpers compute.  None of these touch the
+frozen pipeline-stage signatures in
+:mod:`netcanon.services.migration_pipeline` — they live one layer
+above the pipeline, on the request-shaping / response-shaping side.
+
+Why a separate module?  The route file used to mix request
+validation, capability-matrix shaping, target-profile resolution,
+and pipeline dispatch in one ~750-LOC file.  Lifting these helpers
+into a sibling keeps ``migration.py`` focussed on FastAPI route
+declarations + thin glue, and lets each helper acquire focussed
+unit-test coverage in :mod:`tests.unit.api.test_migration_helpers`
+without spinning up a TestClient.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, Request
+
+from ...migration.codecs.registry import get_codec, list_codecs
+from ...migration.target_profiles import TargetProfile
+from ...models.migration import CodecInfo, MigrationPlanRequest
+from ...storage.base import BaseConfigStore
+
+
+def resolve_adapter_or_422(name: str, side: str):
+    """Return the named adapter or raise a 422 with a helpful message.
+
+    Uses 422 not 404 because the adapter name is REQUEST-PAYLOAD data;
+    callers should fix their body, not their URL.
+    """
+    try:
+        return get_codec(name)
+    except LookupError as exc:
+        raise HTTPException(
+            status_code=422,
+            detail=f"unknown {side} adapter: {exc}",
+        )
+
+
+def resolve_input_text(
+    body: MigrationPlanRequest, storage: BaseConfigStore
+) -> str:
+    """Return the raw config text referenced by *body*.
+
+    Exactly one of ``raw_text`` / ``source_filename`` MUST be set.
+    Raises:
+        HTTPException 422: If both are set or neither is set.
+        HTTPException 404: If ``source_filename`` refers to a file
+            that doesn't exist.
+    """
+    has_text = body.raw_text is not None
+    has_file = body.source_filename is not None
+    if has_text == has_file:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "Exactly one of `raw_text` or `source_filename` is required."
+            ),
+        )
+    if has_text:
+        return body.raw_text or ""
+    try:
+        return storage.get_content(body.source_filename or "")
+    except FileNotFoundError:
+        raise HTTPException(
+            status_code=404,
+            detail=f"source_filename not found: {body.source_filename!r}",
+        )
+
+
+def get_target_profiles(request: Request) -> dict[str, TargetProfile]:
+    """Pull the target-profile registry from ``request.app.state``.
+
+    Profiles are loaded once at app startup (see ``main.py`` lifespan)
+    and exposed through ``app.state.target_profiles``.  ``getattr`` with
+    a default makes this safe under the bare-app fixtures used by some
+    unit tests, which don't populate the full lifespan-loaded state —
+    those tests get an empty dict and the route returns an empty list
+    rather than raising AttributeError.
+
+    Args:
+        request: The current request; only its ``app.state`` is consulted.
+
+    Returns:
+        Mapping of ``"<vendor>/<model>"`` keys to ``TargetProfile``
+        instances.  Empty when no profiles are loaded.
+    """
+    return getattr(request.app.state, "target_profiles", {})
+
+
+def build_codec_info_list(vendors: dict) -> list[CodecInfo]:
+    """Return one :class:`CodecInfo` per registered codec.
+
+    Each entry includes the linked vendor's ``display_name`` (resolved
+    from *vendors*, typically ``request.app.state.vendors``) so the UI
+    can group codecs by vendor without a second round-trip.
+
+    Args:
+        vendors: Mapping of ``vendor_id`` to a vendor record exposing
+            a ``display_name`` attribute.  Pass ``{}`` when the vendor
+            registry isn't populated; missing entries fall back to an
+            empty display name.
+
+    Returns:
+        One :class:`CodecInfo` per name in
+        :func:`netcanon.migration.codecs.registry.list_codecs`, in
+        registry-iteration order.
+    """
+    result: list[CodecInfo] = []
+    for name in list_codecs():
+        codec = get_codec(name)
+        caps = codec.capabilities
+        vendor = vendors.get(caps.vendor_id)
+        result.append(
+            CodecInfo(
+                name=caps.adapter,
+                vendor_id=caps.vendor_id,
+                vendor_display_name=vendor.display_name if vendor else "",
+                version_range=caps.version_range,
+                device_classes=list(caps.device_classes),
+                input_format=getattr(codec, "input_format", "unknown"),
+                direction=getattr(codec, "direction", "bidirectional"),
+                certainty=getattr(codec, "certainty", "experimental"),
+                canonical_model=getattr(codec, "canonical_model", "openconfig-lite"),
+                supported_count=len(caps.supported),
+                lossy_count=len(caps.lossy),
+                unsupported_count=len(caps.unsupported),
+                description=getattr(codec, "description", ""),
+                sample_input=getattr(codec, "sample_input", ""),
+                output_extension=getattr(codec, "output_extension", ""),
+                unsupported_rename_categories=sorted(
+                    getattr(codec, "unsupported_rename_categories", frozenset())
+                ),
+            )
+        )
+    return result
+
+
+def request_has_overrides_or_profile(body: MigrationPlanRequest) -> bool:
+    """Decide whether ``POST /plan`` should engage the rename-aware pipeline.
+
+    Returns ``True`` when *body* carries ANY per-category override map
+    (port / vlan / local-user / SNMP community / SNMPv3 user) OR a
+    ``target_profile`` selection.  Target-profile alone means "run
+    auto-heuristic + return diagnostics the UI can render," and still
+    needs the rename-aware pipeline.
+
+    Legacy callers that supply none of these get the plain
+    :func:`run_plan` path unchanged.
+    """
+    return (
+        body.port_rename_map is not None
+        or body.vlan_rename_map is not None
+        or body.local_user_rename_map is not None
+        or body.snmp_community_rename_map is not None
+        or body.snmpv3_user_rename_map is not None
+        or body.target_profile is not None
+    )