Metadata-Version: 2.4
Name: kproj
Version: 0.13.0
Summary: KiCad project publisher for the SPCoast Hugo site
Project-URL: Homepage, https://github.com/plocher/kproj
Project-URL: Repository, https://github.com/plocher/kproj.git
Project-URL: Issues, https://github.com/plocher/kproj/issues
Author: John Plocher
License-Expression: MIT
License-File: LICENSE
Keywords: hugo,kicad,pcb,release,spcoast,static-site
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: jbom>=7.3.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: behave>=1.2.6; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# kproj

KiCad project publisher for the SPCoast Hugo site.

`kproj` takes a point-in-time snapshot of a KiCad project (renders, schematic SVG/PDF, interactive HTML BOM, fabrication artifacts, KiCad source archive) and publishes it as a version entry on the SPCoast site.

## Installation

```sh
pip install kproj
```

Requires Python ≥3.10. `kproj` needs a local `kicad-cli` install (KiCad 9.x or 10.x) to render/export artifacts, and the iBOM plugin installed into KiCad for the interactive BOM step.

## Usage

```sh
kproj --version
kproj publish [<project-or-dir-or-file>] [options]
kproj list [<project-or-dir-or-file>] [--all] [--site-repo PATH]
kproj delete [<project-or-dir-or-file>] [--version <board_rev>] [--force] [--dry-run] [--no-push] [--site-repo PATH]
```

For `publish`, `list`, and `delete`, run from inside a KiCad project directory, or pass a path to a `.kicad_pro` / `.kicad_sch` / `.kicad_pcb` file, a project directory, or a basename resolved under the KiCad projects root. The project argument defaults to `.` (the current directory).

Pipeline: **render → ibom → fab → publish**. Each release generates board renders, schematic SVG/PDF, the interactive HTML BOM, packages fabrication artifacts, and commits (+ pushes) a version page and its assets into the configured site repo.

### Project/site management commands

- `kproj list [project]` — list published versions for one project in the configured site repo as a one-liner: `project_name [versions...]`. When omitted, the project defaults to `.` and resolves from CWD.
- `kproj list --all` — list all published projects, one line per project, using the same one-line format.
- `kproj delete [project] --version <board_rev>` — delete one published version.
  - If this is the last published version, the command fails unless `--force` is provided.
  - With `--force` in that last-version case, behavior escalates to full-project delete.
- `kproj delete [project]` — non-destructive preview: prints what full-project deletion would remove, then exits non-zero.
- `kproj delete [project] --force` — delete all published versions and project content for that project.
- `--dry-run` works for destructive delete paths and reports what would be removed without writing.
- `--no-push` keeps the delete commit local (batch-friendly), matching publish behavior.

### CLI flags

Run `kproj --help` for the authoritative, up-to-date flag list. As of this writing:

- `--site-repo PATH` — override the local site-repo checkout (highest precedence).
- `--inventory PATH` — inventory CSV to enrich the BOM with curated datasheet names. Unset means kproj never invokes `jbom` and publishes without datasheet deep-links.
- `--fabricator FAB` — jBOM fabricator profile (`generic`, `jlc`, `pcbway`, `seeed`) used for lookup item/header normalization. Default: `jlc`.
- `--ibom-extra-fields FIELDS` — comma-separated iBOM table fields to surface from inventory-enriched data (for example `Details,Description`).
- `--datasheet-library PATH` — local datasheet-library clone used by the advisory publish guard.
- `--datasheet-repo OWNER/REPO` — public repo slug that published datasheet deep-links point at.
- `--version` — print the installed kproj version.
- `--dry-run` — read-only mode: collect findings without writing to the site repo.
- `--republish` / `--force` (publish command) — force artifact regeneration and publish even when unchanged checks would otherwise skip producers.
- `--no-push` — skip `git push` after the site-repo commit (batch-friendly). Run N batch publishes with this flag, then run a final plain `kproj` to flush all queued site commits.
- `-v` / `--verbose`, `-d` / `--debug` — increase logging verbosity. Default and `-v` stderr show a compact findings summary; `-d` additionally emits detailed per-finding rows for debugging.

## Configuration

Every setting (except the project argument) follows a four-tier precedence, highest first:

1. CLI flag
2. `KPROJ_*` environment variable
3. `~/.kproj.yaml`
4. Hardcoded default

`kproj --help` documents the full precedence chain, every `KPROJ_*` environment variable, and a complete `~/.kproj.yaml` example inline.

### First-time setup

If `~/.kproj.yaml` is absent and no inventory is configured, kproj emits a one-time informational hint pointing here — it still publishes successfully, just without datasheet deep-links.

Create `~/.kproj.yaml` to configure kproj for your machine:

```yaml
site_repo: /path/to/your/SPCoast.github.io
no_push: false
kicad_cli: /usr/local/bin/kicad-cli
inventory: /path/to/your/SPCoast-inventory/SPCoast-INVENTORY.csv
datasheet_library: /path/to/your/SPCoast-inventory
datasheet_repo: plocher/SPCoast-inventory
ibom_extra_fields: Details,Description
fabricator: jlc
```

Every key is optional; omit what you don't need to override. `site_repo` and `no_push` control where and how kproj publishes; `kicad_cli` pins a specific executable instead of relying on auto-discovery; `inventory` / `datasheet_library` / `datasheet_repo` configure the datasheet deep-link feature below.
`ibom_extra_fields` controls which inventory-derived columns are surfaced in the generated iBOM table.
`fabricator` controls which jBOM fabricator profile is used for BOM lookup normalization (default `jlc`).

### Datasheet deep-links

When `inventory` is configured, kproj queries `jbom bom --inventory <path> --fabricator <fabricator> -f "reference,datasheet,datasheet_name" -o -` live at publish time and deep-links each curated `Datasheet Name` into the shared datasheet-library repo (view + download URLs) — no PDFs are copied into the site. Lookup parsing accepts both generic and JLC-oriented header names (`Reference`/`Designator`, `Description`/`Comment`, `Lcsc`/`LCSC Part #`). Without an inventory, kproj never invokes `jbom` and publishes without datasheet links (an intentional, advisory-free degraded state, not an error).

## Exit codes

- `0` — clean: published (or refreshed/noop/private-skip) with no error/warning findings.
- `1` — findings present: the same outcomes above, but with at least one error or warning finding (audit, DRC/ERC, etc.). Stderr shows compact counts; detailed rows are in the version page's Markdown body (and on stderr under `-d`).
- `2` — mechanical failure: kicad-cli not found, project resolution failed, or another pipeline step raised.

## Composition with other tools

kproj is one tool in a small ecosystem. The release-lifecycle workflow composes via Makefile (see [`templates/Makefile.kicad`](templates/Makefile.kicad)):

- `jbom fab` — generates fabrication artifacts (`bom.csv`, `pos.csv`, `gerbers.zip`) into `./production/`. Invoked separately by the user before `kproj`.
- `kproj` — reads `./production/` + KiCad project files, publishes a snapshot to the SPCoast site.
- `git tag` + `gh release create` (manual or Makefile-driven) — the release-lifecycle layer, external to kproj.

## Development

- Python ≥3.10; [`uv`](https://docs.astral.sh/uv/) for environment + dependency management (`uv sync`, `uv run`).
- `uv.lock` is committed and authoritative for the development environment. Keep it fresh with `uv lock` whenever dependency inputs change (including local `../jBOM` version shifts). CI validates lock freshness on PRs, and release automation refreshes `uv.lock` after semantic version bumps.
- `pytest` + `behave` for testing; `ruff` + `mypy` for lint/type-checking; `pre-commit` hooks configured.
- `docs/DESIGN.md` has the implementation specs; `docs/adr/` has the Architecture Decision Records; `CONTEXT.md` has the canonical project vocabulary.
- `docs/history.md` has the retired v1-development phase tracker, for archival reference.

## License

MIT — see [`LICENSE`](LICENSE).
