CLI command design

mco

Executes Monkey Change Order JSONC operation files for generated CAD automation.

Purpose

mco is the execution substrate for generated workflows such as mate. It keeps automation intent in JSONC while the executor owns CAD document lifecycle: open on first use, keep documents live during the run, and flush dirty documents on exit.

Usage

altium-cruncher mco init mate.mco.jsonc --force
altium-cruncher mco list
altium-cruncher mco list --json
altium-cruncher mco run mate.mco.jsonc --dry-run
altium-cruncher mco run mate.mco.jsonc --json-output output/mco-result.json
altium-cruncher mco run mate.mco.jsonc --json

Arguments

Area	Contract
`schema`	MCO files use `wn.altium_cruncher.mco.v1`. JSONC comments, trailing commas, and UTF-8 BOM are accepted.
`operations[]`	Ordered operation objects with required `op` then `id`, optional human `message`, required-or-empty `args`, and optional `on_fail` branch target. Generated files write keys in that order for reviewability.
Core ops	`mco.message`, `mco.fail`, and `file.copy`.
Project ops	`project.create`, `schdoc.create`, `pcbdoc.create`, `project.add_document`, `project.add_parameter`, and `project.add_variant`. Project skeletons are intentionally composed from these small operations instead of a bundled project op.
Schematic ops	`schdoc.add_wire`, `schdoc.add_net_label`, and `schdoc.add_component`. `schdoc.add_net_label` accepts optional `orientation` using the Altium Monkey `TextOrientation` enum name or native integer. `schdoc.add_component` accepts optional `designator_style` and `comment_style` objects with `position_mils`, font settings, bold state, and schematic `TextJustification` enum name or native integer.
PCB ops	`pcbdoc.add_text`, `pcbdoc.add_component`, `pcbdoc.arrange_designators`, geometry insertion operations, user-union creation, `pcbdoc.export_layer_step`, and `pcbdoc.add_embedded_3d_model` for placing generated STEP artifacts into an output board. `pcbdoc.add_region` accepts `is_board_cutout` for generated board-profile cutout regions.
Component links	`schdoc.add_component` may set a stable `unique_id`. `pcbdoc.add_component` may set Altium source-link metadata including `source_unique_id`, `source_hierarchical_path`, `source_component_library`, `source_lib_reference`, `source_description`, and explicit `channel_offset` when a workflow actually needs channel linkage. Generated mate plans omit `channel_offset` for simple single-channel projects. The PCB source unique ID is normalized to Altium's backslash-prefixed path form.
Catalog	`mco list` pretty-prints supported operations grouped by functional area with separate required and optional argument lists. `mco list --json` emits `altium_cruncher.mco.operations.a0` metadata with required and optional args; `--output` writes a JSONC catalog for agents and generated-workflow authors.

Output

run prints a colorized human-readable summary by default, including operation count, error count, and one message-first block per operation with the internal op and id shown as secondary detail. Use --json for machine-readable stdout or --json-output to write the structured result while keeping human output on the terminal. Mutation operations return output paths and operation-specific fields in JSON mode. On a normal run, dirty CAD documents are saved after operation execution completes.

{
  "schema": "wn.altium_cruncher.mco.v1",
  "ok": true,
  "dry_run": false,
  "results": []
}

Tests

Coverage lives in tests/test_mco.py. It verifies JSONC parsing, control flow, dry-run handling, CLI init/list/run behavior, document session flushing, schematic and PCB insertion operations, region board-cutout flags, source-link metadata, user unions, text style options, component designator arrangement, library placement, STEP export operation plumbing, and embedded STEP model insertion plumbing.