RigLoom

Plan every internal PC connection before assembly.

RigLoom is an offline wiring planner and safety linter for fans, pumps, 5 V ARGB, 12 V RGB, internal USB, case front I/O, sensors, and accessory power. It reads a real build description, solves compatible assignments, propagates passive-splitter loads, checks declared limits, and produces a wiring map with repair steps.

It is not a parts-price site, a motherboard lane database, or RGB control software. RigLoom answers the smaller question that still ruins build day:

Where does every internal cable go, and is that connection electrically and physically safe?

Live demo | 中文说明 | Example build | Research

What works today

• Constraint-based routing instead of fixed sample output.
• Strict separation of 5 V 3-pin ARGB and 12 V 4-pin RGB.
• Connector capability checks such as PWM control, DC control, tach feedback, and lighting data.
• Per-source plug, current, and LED limits with configurable safety headroom.
• Passive splitter load propagation through drawFrom.
• Powered hubs that expose independent output capacity after their own input and power leads are routed.
• BIOS-critical CPU fan header policy.
• Explicit pinned connections for cables you already know.
• Deterministic text, JSON, Markdown, HTML, and SVG reports.
• Browser workbench and Node.js CLI sharing the same dependency-free solver.
• Exit code 1 for an unsafe or unroutable build and 2 for invalid input.

Try it

Requirements: Node.js 20 or newer. RigLoom has no runtime dependencies.

git clone https://github.com/KanadeK/rigloom.git
cd rigloom
node bin/rigloom.js check examples/sff-rgb-studio.json
node bin/rigloom.js plan examples/sff-rgb-studio.json --format html --output rigloom-report.html

Expected safe result:

RigLoom PASS | 21/21 connected | 0 errors | 0 warnings

Prove that the linter fails closed:

node bin/rigloom.js check examples/unsafe-argb.json

Expected result and exit code:

RigLoom FAIL | 0/1 connected | 1 errors | 0 warnings
ERROR PINNED_VOLTAGE_MISMATCH: ...

Create your own editable build file:

node bin/rigloom.js init my-build.json
node bin/rigloom.js plan my-build.json

CLI

rigloom plan <build.json> [--format text|json|markdown|html] [--output <file>]
rigloom check <build.json> [--json]
rigloom init [output.json] [--template sff|unsafe-argb|usb-starved|repaired-usb]
rigloom connectors [--json]
rigloom explain <connector-id>

The executable can be linked locally with npm link, or invoked as node bin/rigloom.js without installing anything.

Build format

A build has sources supplied by the motherboard, PSU, or existing controllers, plus component requirements:

{
  "$schema": "./schema/rigloom.schema.json",
  "schemaVersion": 1,
  "name": "Small workstation",
  "sources": [
    {
      "id": "mb.cpu_fan",
      "label": "CPU_FAN",
      "connector": "fan-pwm-4pin",
      "traits": ["pwm-control", "tach-read", "bios-critical"],
      "reservedFor": ["cpu-cooling"],
      "capacity": { "maxDevices": 1, "maxCurrentMa": 1000 }
    }
  ],
  "components": [
    {
      "id": "cooler",
      "label": "Tower cooler",
      "requirements": [
        {
          "id": "fan",
          "connector": "fan-pwm-4pin",
          "currentMa": 240,
          "requiredTraits": ["pwm-control", "tach-read"],
          "role": "cpu-cooling",
          "preferredSources": ["mb.cpu_fan"]
        }
      ]
    }
  ]
}

Editor validation is provided by schema/rigloom.schema.json. The full model, hub behavior, and passive load propagation are documented in docs/CONNECTOR_MODEL.md.

Hubs and splitters

A component may expose outputs. A powered hub gives those outputs their own declared capacity. A passive splitter uses drawFrom so every downstream fan or LED load is added to its upstream requirement:

{
  "id": "fan-splitter",
  "label": "Passive three-way fan splitter",
  "requirements": [
    {
      "id": "input",
      "connector": "fan-pwm-4pin",
      "requiredTraits": ["pwm-control", "tach-read"]
    }
  ],
  "outputs": [
    {
      "id": "outputs",
      "connector": "fan-pwm-4pin",
      "drawFrom": "input",
      "traits": ["pwm-control", "tach-read"],
      "capacity": { "maxDevices": 3, "maxCurrentMa": 1000 }
    }
  ]
}

RigLoom refuses a component's input from its own output, preventing self-powered loops.

Why this is a separate project

Existing category	What it does	RigLoom boundary
PCPartPicker-style tools	Select parts, prices, and broad compatibility	Models the actual internal leads and header budget of one build
MoboMaps	Visualizes motherboard PCIe lane routing	Does not duplicate lane maps; routes fans, lighting, USB, front I/O, and hubs
OpenRGB, FanControl, CoolerControl	Controls attached hardware at runtime	Plans connections before assembly; never writes device firmware or fan curves
Vendor wiring diagrams	Show one vendor ecosystem	Uses an open vendor-neutral JSON model and explains mixed-component conflicts

The July 2026 competitor and community scan, including searches that caused the PCIe-lane idea to be rejected, is preserved in docs/RESEARCH.md.

Safety scope

RigLoom checks only the facts in the input file. It cannot discover undocumented board limits, proprietary connector pinouts, cable quality, PSU rail design, physical reach, or case clearance.

• Copy ratings from the exact motherboard and component manuals.
• Treat missing current ratings as warnings, not permission.
• Never force a keyed connector.
• Never connect 5 V ARGB to 12 V RGB.
• Use only cables intended for the exact modular PSU model.
• Disconnect AC power before changing internal cabling.

RigLoom is a planning aid, not a replacement for manufacturer instructions or a qualified technician.

Reports

node bin/rigloom.js plan examples/sff-rgb-studio.json --format json --output plan.json
node bin/rigloom.js plan examples/sff-rgb-studio.json --format markdown --output plan.md
node bin/rigloom.js plan examples/sff-rgb-studio.json --format html --output plan.html

JSON is intended for automation. HTML is self-contained and includes the solved wiring graph. Every format is derived from the same plan object.

Acceptance

Release maintainers should use Node.js 24 and run the complete release gate:

npm ci
npm run release:check

The gate performs:

• syntax and source hygiene checks;
• unit, integration, CLI, report, and browser-core tests;
• line, function, and branch coverage thresholds;
• safe and deliberately unsafe fixture exit-code checks;
• deterministic JSON report comparison;
• JSON Schema and documentation checks;
• static-site build;
• secret scan;
• npm package dry run;
• release asset creation and SHA-256 manifest;
• Git author and Co-authored-by checks when Git history exists.

CI repeats source checks and the full test suite on Node.js 20, 22, and 24. The Node.js 24 job also enforces coverage thresholds and builds the static workbench.

If acceptance fails

Start with the failing command printed by the gate, then use docs/REPAIR.md.

npm run check
npm test
npm run test:coverage
node bin/rigloom.js check examples/sff-rgb-studio.json
node bin/rigloom.js check examples/unsafe-argb.json
npm run site
npm run pack:release

Do not suppress an unsafe fixture failure. Its exit code must remain 1. Do not lower coverage thresholds to make a release green. Repair the implementation or fixture and rerun npm run release:check.

Architecture

JSON build
   |
validation and normalization
   |
connector compatibility candidates
   |
deterministic backtracking solver
   |
load propagation and policy checks
   |
text / JSON / Markdown / HTML / SVG

See docs/ARCHITECTURE.md for module boundaries and invariants.

Contributing

New connector types, real manual-derived profiles, safer diagnostics, and reproduction fixtures are welcome. A profile contribution must cite the exact manual and page and must not copy copyrighted diagrams. Read CONTRIBUTING.md before opening a pull request.

License

MIT. See LICENSE.