CLI command design

pcbdoc

Authors PCB documents through generated MCO operations.

Purpose

pcbdoc creates small blank board files for fixtures and generated projects. The initial release supports simple rigid boards, rectangular board outlines, generated copper/dielectric layer stacks, and optional standard mechanical layer kind initialization.

Usage

altium-cruncher pcbdoc create
altium-cruncher pcbdoc create pcbdoc_create.jsonc
altium-cruncher pcbdoc create board.PcbDoc
altium-cruncher pcbdoc create board.PcbDoc --layers 4 --width-mils 3000 --height-mils 2000
altium-cruncher pcbdoc create board.PcbDoc --mechanical-layer-profile standard_component_pairs --json
altium-cruncher pcbdoc create board.PcbDoc --layer-stack-template 2-layer

Arguments

Argument	Contract
`create`	With no target, writes `pcbdoc_create.jsonc` when no config exists. A later no-target run loads that config and creates the PCB document.
`create config.jsonc`	Loads or initializes a PcbDoc create config using schema `altium_cruncher.pcbdoc.create.config.a0`.
`create file`	Legacy direct mode. Destination `.PcbDoc`. Paths are passed into generated MCO as `file`.
`--layers`	Generated rigid copper layer count when no `--layer-stack-template` is supplied. The default is two copper layers.
`--layer-stack-template`	Uses an Altium Monkey built-in layer-stack template instead of generated rigid stack rows.
`--width-mils`, `--height-mils`	Rectangular board outline size in mils.
`--mechanical-layer-profile`	`none` or `standard_component_pairs`. The standard profile expands into explicit mechanical layer names, enabled states, layer pairs, and layer kinds in the generated MCO.
`--emit-mco`, `--force`, `--dry-run`, `--json`, `--json-output`	Follow the shared MCO command semantics for operation emission, overwrite, non-mutating planning, stdout JSON, and sidecar JSON report output.

Config Shape

The A0 config is the same child object shape used by prjpcb.pcb, with a top-level schema field. Generated configs include a rectangular board outline, generated rigid layer stack, editable single mechanical_layers, and grouped mechanical_layer_pairs with top and bottom layer rows. The template header documents valid mechanical layer ids, indexes, default names, and mechanical layer kind enum values.

MCO Shape

pcbdoc create compiles to one pcbdoc.create operation. Generated rigid stacks are passed as rigid_stack. The standard mechanical profile or explicit config rows are expanded into mechanical_layers, mechanical_layer_pairs, and mechanical_layer_kinds rather than stored as an opaque profile token.

Stackup Scope

This release does not import .stackup or .stackupx files into new PcbDoc files. Existing Altium Monkey samples prove typed layer-stack model authoring and stackup export/readback, while direct stackup-file to PcbDoc replacement entries remain future Altium Monkey work.

Output

The first config-first run writes the sample JSONC config only; the next run uses that config to write the requested .PcbDoc unless --dry-run is used. Tests reparse generated boards and verify copper layer names plus mechanical layer kind readback.

Tests

Coverage lives in tests/test_mco.py and tests/test_document_create_commands.py. It verifies generated rigid stack creation, standard mechanical layer-kind profile expansion, command JSON output, and Altium Monkey reparse of generated boards.