project-lib

Usage

kicad-cruncher project-lib project.kicad_pro
kicad-cruncher project-lib project.kicad_pro -o local-library
kicad-cruncher project-library project.kicad_pro --include-asset-scan
kicad-cruncher project-local-lib project.kicad_pro --validate-kicad-cli
kicad-cruncher project-lib project.kicad_pro --symbol-library-dir local-symbols --footprint-library-dir local-footprints
kicad-cruncher project-lib project.kicad_pro --include-models
kicad-cruncher project-lib project.kicad_pro --no-update-library-tables

Arguments

file accepts a .kicad_pro project. If omitted, the command auto-detects exactly one .kicad_pro in the current directory.

-o selects the output directory. Without -o, artifacts are written under ./local-library/. project-library, project-local-lib, and local-library are aliases for the same command. The default symbol folder is the .kicad_pro stem, and the default footprint folder is <.kicad_pro stem>.pretty. --symbol-library-dir and --footprint-library-dir override those folder names. --symbol-library-name and --footprint-library-name override the project table nicknames; when omitted, the nicknames come from the generated library folder names. --no-update-library-tables extracts artifacts without editing sym-lib-table or fp-lib-table.

The command always uses project-local extraction mode: schematic symbols preserve metadata and project-specific variants, while PCB footprints are deduplicated by footprint library link down to the reusable common footprint set. Repeated embedded copies of the same schematic library symbol are collapsed by symbol member name so copied sheets do not create _2, _3, ... symbol files. KiCad-generated multipart alias members such as PART_1 are also collapsed when a base PART symbol exists.

--no-embed-models disables board-embedded model payload rehydration in extracted footprints. --no-embed-external-models disables resolving external STEP/STP model paths into extracted footprints. --include-models additionally writes decoded embedded STEP/STP model files under models/, preserving model filenames instead of de-duplicating solely by payload hash. --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 preservation, model path classification, external STEP/STP embedding, metadata bundle construction, project library table editing, 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.

By default the command ensures project-local sym-lib-table and fp-lib-table entries exist for the generated symbol folder and footprint .pretty library. Existing nicknames are left unchanged. Generated symbol-library files have their internal symbol name normalized to the file member name, and their Footprint property is relinked to the generated footprint-library nickname when that footprint was extracted. The command does not relink source schematic symbols, relink source PCB footprints, or rewrite project text variables.

Output

The selected output directory contains a self-contained project-local library bundle:

• <project-stem>/*.kicad_sym: metadata-preserving single-symbol KiCad symbol library files unless --symbol-library-dir selects another folder.
• <project-stem>.pretty/*.kicad_mod: reusable standalone KiCad footprints, deduplicated by footprint library link across repeated placed instances unless --footprint-library-dir selects another folder.
• models/*.{step,stp}: optional decoded embedded STEP/STP model payloads from the full project when --include-models or --all-embedded-models is used.
• 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.
• project_lib_manifest.json: kicad_cruncher.project_lib_manifest.a0 artifact index with counts, relative output paths, mode, source project, project library table actions, 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.

megamaid handles cleaned lib_cruncher ingestion assets. project-lib handles metadata-preserving project-local assets. health handles broader asset diagnostics without extracting libraries.

Roadmap

Remaining project-local library hardening is tracked by docs/library/requirements/library-req-001-extraction-hardening.md. The deferred source-mutation path must be explicit, opt-in, dry-run or patch reviewable, and test-covered before source schematic symbols or PCB footprints are relinked to generated project-local libraries.

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 project-lib against a temporary copy of the sanitized 4-ch backplane corpus fixture and verify manifest schema, project-stem output directories, CLI output-directory overrides, metadata schema, project-local preservation mode, footprint library-link dedupe, local table updates, idempotency, and aliases.