Metadata-Version: 2.5
Name: cmk-werk-zeug
Version: 0.4.0
Summary: cmk-werk-zeug
Author-email: Benedikt Seidl <benedikt.seidl@checkmk.com>, Frans Fürst <frans.fuerst@checkmk.com>
License-File: LICENSE
Requires-Python: <4,>=3.12
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: argcomplete>=3.5
Requires-Dist: jira>=3.10.5
Requires-Dist: psycopg2-binary>=2.9.11
Requires-Dist: pydantic>=2
Requires-Dist: python-jenkins>=1.8.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: secretstorage>=3.5.0
Requires-Dist: sqlalchemy>=2.0.45
Requires-Dist: textual>=7.3.0
Requires-Dist: trickkiste>=0.3.7
Requires-Dist: vcrpy>=8.1.1
Description-Content-Type: text/markdown

# CWZ - CMK-Werk-Zeug

This is both a collection of tools and shared libraries created for (but not limited to) Checkmk development
and a 'collector' for other tools located in different repositories.


## What you get

### `cmk-components`

A CLI for querying and validating component and code ownership details of the `check_mk` (mostly) repository.

**Use cases:**

- Browse all components interactively (TUI, default when no subcommand is given): `tui`
- List all known components: `list` (alias: `ls`)
- Show full details of one or more components: `info [COMPONENT ...]`
- Show members/owners of a component: `members [COMPONENT ...]`
- Show which paths belong to a component: `paths <COMPONENT> [...]`
- Look up who owns a given file or directory: `owners <PATH> [...]`
- Find which component a path belongs to: `component <PATH> [...]`
- List all `OWNERS` config files in the repo: `config-files`
- Show your own responsibilities (components and paths): `my-responsibilities` (alias: `me`)
- Validate the code-owners configuration for consistency: `validate-config`
- Check overall consistency by comparing reality (`git-blame` and commit frequency) with defined ownership: `check-plausibility`

**Credentials**: resolved in folowing order:
- `~/.netrc` (looking for the hostname extracted from `gerrit-url`)
- environment variables (via `--gerrit-username-var` / `--gerrit-api-token-var`).
- GNOME keyring
- interactive prompt (if not in dumb terminal mode), with option to store credentials in the keyring.

**Source for ownership details**: `--gerrit-url`, `--project-name` (defaults to `check_mk`), `--branch` (useful for change valildation)
to point at a different Gerrit instance or branch.

**Output modes** (`--mode`): `rich` (default in a terminal), `json`, `script` (default when
stdout is not a TTY — suitable for piping).

**Caching** (`--cache-mode auto|always|never`): a locally cached collection of component and
ownership information stored at `~/.cache/cwz/cmk-components.json` will be used in `auto` (default)
mode if remote git commit still matches or when in `always` mode. In `never` mode, the cache will be
ignored and updated with the latest data from Gerrit.


### `cmk-check-plugins`

Validates Checkmk check plugins (SNMP- and agent-based) against recorded SNMP walks and agent output
files, reporting section parsing, discovery, and check results.

**Inputs**: `--snmp-walks <PATH ...>` and `--agent-outputs <PATH ...>` point at the data files to
validate against; all Checkmk plugins are loaded from the local checkout.

**Filtering**: `--filter-sections <name,...>` restricts to specific sections (case-insensitive),
`--ignore-walks <name,...>` skips named walk files, `-a`/`--show-all` shows both detected and
non-detected plugins.

**Error handling**: `--raise-error <type,...>` (empty = all) raises selected error types,
`--ignore-error <type,...>` swallows selected exception types, `--error-file [PATH]` writes
problematic walk paths (default `errors.txt`).

**Output**: `--suppress-duration` drops timing info. Results are written to `results.json` (section
tables, discovery and check results) plus a `profile_stats.prof` cProfile dump.


### `cmk-infect`

Syncs an installed site with your local checkout just by placing hard links.
* Pro: deployment in 0s, stays in-sync automatically!
* Con: might fail for a lot of reasons, works only for Python-only code!

**Usage**: `cmk-infect <target_dir> [site]` - `target_dir` is the OMD version root (e.g.
`/omd/versions/default`); `site` defaults to `$SITE` or a local `.site` file. The ancestor branch
(`master`, `2.5.0`, `2.4.0`, ...) and its path mapping are auto-detected.

**Options**: `--mkp` deploy into the site's `local/` tree instead of the version, `--copy` copy
instead of hardlink, `--info` show what would be deployed without touching files, `--test`
sanity-check that every tracked file maps to an existing deploy path, `--include <PATH ...>` /
`--exclude <regex>` restrict the file set.

**Caveat**: skips non-Python files, tests, and known non-deployable packages; missing ACLs on the
target are offered to be fixed via `sudo setfacl`.

In order to avoid unnessessary conflicts, sync your checkout with your local site first:
```
git fetch origin `cat /opt/omd/versions/3.0.0-2026.07.21.pro/share/doc/COMMIT`
git rebase -i FETCH_HEAD
```

### `update-gerrit-changes`

Shows a table of local Git commits and their sync status against remote Gerrit changes (matches a
remote revision, has pending updates, or differs from all revisions).

Run inside a Checkmk Git checkout; it auto-detects the ancestor branch (`master`, `2.5.0`, `2.4.0`,
…). Requires VPN connectivity and Gerrit credentials.

**Options**: `--gerrit-url` (default `https://review.lan.tribe29.com`), `--project-name`
(default `check_mk`), `--branch` (default `master`), `--gerrit-username-var` /
`--gerrit-api-token-var` (env var names), `--store-credentials` (persist to keyring), plus the
common logging args (`-l`/`--log-level`, `--log-file`).


### `worklog-from-fs` (a.k.a. `forgot-to-track-time-again`)

Estimates daily 'computer usage' by scanning filesystem modification timestamps and rendering a
20-day activity graph (time range and intensity per day).

**Usage**: takes one optional positional `<path>` to scan (defaults to `~`). Browser caches and
Signal data are excluded to reduce noise; only files modified within the current year are considered.


### `ci-build-metrics`

Fetches finished Jenkins build logs and extracts queryable CI build metrics into a PostgreSQL
database.

**Subcommands**:
- `fetch` (`f`) — fetch build info and logs of completed Jenkins builds and store them compressed locally.
- `create-digests` (`d`) — extract critical data about (mostly failed) builds into digest files.
- `index` — build an index dataset of static query data (e.g. timestamps) for fast lookup.
- `fuse` — enrich digests by inferring upstream/downstream relationships and combining build causes.
- `export` (`e`) — export all digest data to PostgreSQL.
- `update` — convenience pipeline running `fetch` → `create-digests` → `index` → `fuse` → `export`.
- `info` (`i`) — print detailed info about specific builds.
- `report` — generate a queryable report of builds matching filter criteria.
- `spreadsheet` — render report data into an ODF spreadsheet.
- `issue-figures` — show usage stats for each regex in the known-issues file.

**Common filters**: `--date-from` / `--date-to` (default `--date-from` is last Saturday),
`--include <regex>` / `--exclude <regex>`, `--max-results <N>`, `--rebuild` / `--refresh`,
`-v`/`--verbose`, `--markdown`.

**Config & storage**: `--jenkins-url` (default `https://ci.lan.tribe29.com`), `--base-dir`
(default `~/.cache/ci_metrics`), `--builds-dir`, `--max-processes` (default 10),
`--known-issues-file` (YAML mapping regexes to issue metadata, default `known_issues.yaml`),
`--report-file`, `--failed-builds-file`. Jenkins credentials come from the common Jenkins CLI args
(env/config); export targets a local PostgreSQL instance (see Install).


## Install

You either clone the cwz repository (`ssh://review.lan.tribe29.com:29418/cmk-werk-zeug`) and make it's tools available
via `uv` or you install the pip package:

```
pipx install cmk-werk-zeug
```

For ci_build_metrics you need PostgreSQL installed
```
sudo apt install postgresql postgresql-contrib postgresql-server-dev
```
