CLI command design

mate

Generates beta mating-board projects from a human-authored DUT projection config.

Purpose

mate creates a board that physically mates to a source DUT board. The command compiles a JSONC config into an Altium-specific Monkey Change Order, then can execute that MCO to create the output project. The Cricket Node example is the first public reference workflow and represents the initial beta release surface for fixture/debug testing.

The config remains the human-authored source of truth. The generated MCO is derived output and may contain resolved coordinates, nets, library file paths, and primitive-level Altium operation arguments. Broader header-style, multi-pin connector, richer library metadata, and GUI-assisted workflows remain future work.

Usage

altium-cruncher mate
altium-cruncher mate --dry-run
altium-cruncher mate --launch
altium-cruncher mate plan --output-mco mate.mco.jsonc --force
altium-cruncher libraries mating_parts
altium-cruncher mate libs mating_parts --json

With no config in the current directory, mate writes mate.a0.jsonc and exits. With a config present, mate writes the derived mate.a0.mco.jsonc and runs it. mate prints a human-readable MCO execution summary by default; use --json or --json-output when a machine-readable execution report is needed. mate plan writes the MCO only, and if no config exists it behaves like initialization. The generic libraries command scans folders for SchLib symbols and PcbLib footprints so users can confirm the names used by mate_component actions; mate libs remains a shortcut to the same scanner.

Arguments

Area	Contract
`--config`	Optional config path. The default lookup is `mate.a0.jsonc`, then legacy `mate.jsonc`.
`source`	Identifies the DUT project or PCB document. The planner extracts positions, source layers, nets, component footprints, free pads, board outline, and board origin from source files.
`libraries`	Declares recursive search roots for mating SchLib/PcbLib files. Roots are config-relative unless absolute. Duplicate symbol or footprint names are rejected unless the config is made more specific in a future slice.
`output`	Controls generated project path, filenames, overwrite policy, schematic sheet style, board outline/origin preservation, and layer-stack template.
`projections`	Describe which source objects are selected and which output actions are generated: mate component placement, source reference graphics, board outline/cutouts, PCB labels, and artifacts.
`artifacts.pcb_layer_step`	Uses the standalone `pcb-layer-step` config shape for source-layer STEP generation. Mate only routes this config to the MCO exporter and inserts the resulting artifact when requested.

Output

The default output directory is output. A run creates a project with schematic, PCB, copied mating libraries, placed mating components, arranged component designators, optional source-reference graphics, actual board cutouts, schematic wires/net labels, a user union named MATE_FEATURES, loose PCB net-label columns, and requested artifacts such as PCB layer STEP outputs. Generated MCO files compose project setup from small operations: project.create, schdoc.create, pcbdoc.create, and project.add_document. The planner emits schematic mutations together before PCB mutations so the generated script is easier to inspect.

The Cricket Node example at examples/mate/cricket-node commits the DUT source project and minimal mating_parts/ libraries but intentionally does not commit mate.a0.jsonc. The generated config selects TP*, M1-4, and matching free NPTH alignment holes; resolves the named mating symbols/footprints from mating_parts/; makes the output board larger than the DUT bounds; projects source pad outlines on MECHANICAL_1; projects source outline/cutouts; emits loose board-edge labels; and inserts a hashed bottom-layer STEP artifact at the configured output-board height.

Tests

Coverage lives in tests/test_mate.py. It verifies template generation, source inspection, selector expansion, recursive library scanning through the generic scanner, name-based part resolution, legacy manifest compatibility, CLI default/plan/dry-run behavior, Cricket example planning, generated MCO shape, Sch/PCB source-link metadata, labels, source-reference graphics, board projection, and STEP artifact operation generation.