CableMancer

Infrastructure as code for the cable behind your desk.

中文说明 · Configuration · Troubleshooting · Why this is different

A USB-C setup can look right while one cable, dock path, or missing feature claim makes it impossible. CableMancer reads a declarative graph of ports and links, finds the widest viable path for every power, data, and display requirement, and names the exact bottleneck.

It is a real offline analyzer, not a compatibility checklist or UI mockup. The runtime has zero third-party dependencies and never probes hardware or calls a network service.

flowchart LR
  charger[100 W charger] -->|100 W| dock[USB4 dock]
  dock -->|90 W PD| laptop[Laptop]
  laptop -->|25.92 Gbps display| dock
  dock -->|25.92 Gbps| monitor[4K monitor]
  laptop -->|40 Gbps data| dock
  dock -->|10 Gbps| ssd[External SSD]

Loading

Try it in 30 seconds

python -m pip install .
cablemancer demo --output-dir cablemancer-demo
cablemancer analyze cablemancer-demo/setup.json

The built-in demo proves three independent declared paths:

CableMancer: One-cable USB4 desk
Status: PASS (3/3 requirements passed)

[PASS] Charge the laptop
  Required: 65 w | Delivered: 90 w
  Limiting links: dock-power-path

[PASS] Drive the 4K monitor
  Required: 17.82 gbps | Delivered: 25.92 gbps

[PASS] Reach the external SSD
  Required: 10 gbps | Delivered: 10 gbps

Now run a valid setup that cannot meet its request:

cablemancer analyze examples/power-bottleneck.json

Status: FAIL (0/1 requirements passed)
Required: 65 w | Delivered: 45 w
Code: CAPACITY_SHORTFALL
Limiting links: charging-cable

The process exits 2, so the same check can gate a pull request while still producing a complete report.

What it actually does

• Models cables, ports, adapters, and internal dock paths as directed links.
• Keeps power, data, and display capacities separate.
• Requires units and opaque feature claims to match on every traversed link.
• Selects the widest viable path, then reports its bottleneck links.
• Distinguishes NO_PATH, UNIT_MISMATCH, FEATURE_MISSING, and CAPACITY_SHORTFALL.
• Emits deterministic text, JSON, Markdown, and Mermaid evidence.

cablemancer validate examples/one-cable-desk.json
cablemancer analyze examples/one-cable-desk.json --format json
cablemancer analyze examples/one-cable-desk.json \
  --format markdown --output report.md --diagram topology.mmd

Exit codes are stable: 0 means valid and passing, 1 means invalid input or I/O failure, and 2 means valid analysis with at least one failed requirement.

What a PASS does not mean

CableMancer checks user-declared evidence. It does not test electrical quality, negotiate with devices, certify safety, infer capabilities from a connector name, or guarantee that a real setup works. USB-IF compliance tools and real-device testing remain the appropriate evidence for those claims.

Each requirement is independent in v0.1. Shared power and bandwidth budgets are intentionally out of scope.

Why another USB-C project?

Live inspectors such as WhatCable, usbeehive, and libtypec answer “what does this attached machine expose?” Product pickers answer “what should I buy?” CableMancer answers a different, reviewable question: “Do the facts declared for this arbitrary multi-hop design support every requirement?”

The bounded prior-art audit, rejected ideas, adjacent projects, and official USB-IF sources are recorded in docs/research.md.

Examples and documentation

• One-cable desk: three passing paths.
• Power bottleneck: valid config, exit 2.
• Display feature gap: missing dp_tunnel evidence.
• Invalid reference: boundary error, exit 1.
• Configuration reference: complete schema and path semantics.
• Troubleshooting and repair: every acceptance gate and its next command.

Development and release gate

python -m unittest discover -s tests -v
python scripts/verify.py

scripts/verify.py runs the full tests, bytecode compilation, deterministic demo comparison, wheel build, package-content checks, and an installed-wheel smoke test in a fresh virtual environment. CI runs the same gate on Linux, macOS, and Windows.

See CONTRIBUTING.md for changes and SECURITY.md for vulnerability reports. CableMancer is available under the MIT license.