megamaid

Usage

kicad-cruncher megamaid project.kicad_pro -o output/megamaid
kicad-cruncher megamaid project.kicad_pro --dedupe fingerprint
kicad-cruncher megamaid project.kicad_pro --validate-kicad-cli

Arguments

file accepts a .kicad_pro project. If omitted, the command auto-detects exactly one .kicad_pro in the current directory. Schematic-only and PCB-only inputs are intentionally not accepted in this first public workflow because the extraction bundle needs the project root, local libraries, board file, and schematic files together.

-o selects the output directory. Without -o, artifacts are written under ./output/megamaid/. lib-extract is the separate cleaned library ingestion command.

The command reuses internal library extraction mode for symbols and footprints, then adds a broader embedded-asset pass that decodes board, footprint, schematic, symbol-library, and worksheet payloads. It also writes the same design-review bundle as design under design_review/.

--dedupe name collapses repeated assets by library name. --dedupe fingerprint collapses by stripped serialized content. --no-embed-models disables board-embedded model payload rehydration. --no-embed-external-models disables resolving external STEP/STP model paths into extracted footprints. --all-embedded-models scans the whole project and writes every embedded STEP/STP payload. --include-asset-scan includes the full model-reference scan in the metadata JSON. --validate-kicad-cli asks KiCad CLI to parse/upgrade the generated libraries, and --kicad-cli selects the executable.

Ownership

The KiCad parsing, metadata stripping, model path classification, external STEP/STP embedding, metadata bundle construction, and KiCad CLI validation helpers are owned by kicad-monkey. kicad-cruncher owns command-line ergonomics, output directory layout, manifest writing, README writing, logging, and exit status.

The command is non-destructive. It does not edit the source project, update sym-lib-table or fp-lib-table, relink schematic symbols, relink PCB footprints, or rewrite project text variables. Project-local table editing belongs to project-lib.

Output

The selected output directory contains a self-contained extraction bundle:

• symbols/*.kicad_sym: one single-symbol KiCad symbol library file per extracted symbol record.
• footprints.pretty/*.kicad_mod: one standalone KiCad footprint per extracted footprint record.
• models/*.{step,stp}: decoded embedded STEP/STP model payloads required by the extracted footprint records, or every embedded payload when --all-embedded-models is used.
• embedded_assets/embedded_files/*: decoded compressed KiCad (embedded_files ...) payloads from boards, placed footprints, schematics, footprint libraries, and symbol libraries.
• embedded_assets/schematic_images/*, embedded_assets/pcb_images/*, and embedded_assets/worksheet_bitmaps/*: decoded bitmap payloads from schematic, PCB, footprint, and worksheet image containers.
• design_review/<project-stem>_design.json: kicad_monkey.design.a0 design JSON.
• design_review/<project-stem>_netlist.json: kicad_monkey.netlist.a0 netlist JSON.
• design_review/<project-stem>_netlist.net: kicad-cli-style S-expression netlist.
• design_review/design_review_manifest.json: nested kicad_cruncher.design_review_manifest.a0 artifact index.
• design_review/schematics/*.svg: one enriched schematic SVG per concrete hierarchy instance.
• design_review/pcb/copper_layers/*__review.svg: one enriched PCB review SVG per copper layer when a board is present.
• library_extraction.json: kicad_cruncher.library_extraction_bundle.a0 metadata with raw fields, canonical identity fields, source paths, source references, model-reference diagnostics, and optional project asset scan when --include-asset-scan is used.
• megamaid_manifest.json: kicad_cruncher.megamaid_manifest.a0 artifact index with counts, relative output paths, embedded asset records, nested design-review artifact records, mode, source project, and optional KiCad CLI validation results.
• README.md: short human-readable summary for agents and reviewers.

The library_extraction.json metadata follows docs/contracts/library_extraction_bundle.a0.schema.json. raw_fields is the raw KiCad parameter/property map with source key spelling preserved; canonical_fields is derived from those fields using case-insensitive alias matching for part fields such as mpn, mfg, value, description, and cad-reference.

The top-level manifest records the design_review directory, nested manifest, README, design JSON, netlist JSON, S-expression netlist, component count, net count, schematic SVG count, PCB SVG count, and relative SVG paths.

This command is intended for full project dissection and archival review. Clean reusable CAD ingestion is handled by lib-extract; metadata-preserving project-local extraction is handled by project-lib; broader asset diagnostics are handled by health.

Tests

L0 public CLI tests verify the command appears in root help, command help starts, and the manifest/design-doc inventory stays synchronized. L3 public workflow tests run megamaid against the sanitized 4-ch backplane corpus fixture and verify the manifest schema, output directories, metadata schema, symbol/footprint/model counts, internal stripping mode, embedded asset records, design JSON, netlist artifacts, schematic SVGs, and PCB review SVGs. The optional KiCad CLI validation path is covered by kicad-monkey L2 tests and can be exercised through --validate-kicad-cli when a local KiCad install is available.