kubed-mcp 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. kubed_mcp-0.0.1/.gitattributes +6 -0
  2. kubed_mcp-0.0.1/.github/CODEOWNERS +3 -0
  3. kubed_mcp-0.0.1/.github/assign.yml +1 -0
  4. kubed_mcp-0.0.1/.github/copilot-instructions.md +126 -0
  5. kubed_mcp-0.0.1/.github/dependabot.yml +59 -0
  6. kubed_mcp-0.0.1/.github/instructions/github-workflows.instructions.md +152 -0
  7. kubed_mcp-0.0.1/.github/instructions/python.instructions.md +54 -0
  8. kubed_mcp-0.0.1/.github/instructions/yaml.instructions.md +28 -0
  9. kubed_mcp-0.0.1/.github/workflows/lint.yml +97 -0
  10. kubed_mcp-0.0.1/.github/workflows/package.yml +143 -0
  11. kubed_mcp-0.0.1/.github/workflows/pr.yml +118 -0
  12. kubed_mcp-0.0.1/.github/workflows/publish.yml +282 -0
  13. kubed_mcp-0.0.1/.github/workflows/quality.yml +95 -0
  14. kubed_mcp-0.0.1/.github/workflows/test.yml +132 -0
  15. kubed_mcp-0.0.1/.github/zizmor.yml +73 -0
  16. kubed_mcp-0.0.1/.gitignore +43 -0
  17. kubed_mcp-0.0.1/AGENTS.md +59 -0
  18. kubed_mcp-0.0.1/CHANGELOG.md +32 -0
  19. kubed_mcp-0.0.1/CONTRIBUTING.md +74 -0
  20. kubed_mcp-0.0.1/LICENSE +21 -0
  21. kubed_mcp-0.0.1/PKG-INFO +79 -0
  22. kubed_mcp-0.0.1/README.md +44 -0
  23. kubed_mcp-0.0.1/kubed/mcp/__init__.py +12 -0
  24. kubed_mcp-0.0.1/kubed_mcp.egg-info/PKG-INFO +79 -0
  25. kubed_mcp-0.0.1/kubed_mcp.egg-info/SOURCES.txt +31 -0
  26. kubed_mcp-0.0.1/kubed_mcp.egg-info/dependency_links.txt +1 -0
  27. kubed_mcp-0.0.1/kubed_mcp.egg-info/requires.txt +12 -0
  28. kubed_mcp-0.0.1/kubed_mcp.egg-info/scm_file_list.json +28 -0
  29. kubed_mcp-0.0.1/kubed_mcp.egg-info/scm_version.json +8 -0
  30. kubed_mcp-0.0.1/kubed_mcp.egg-info/top_level.txt +1 -0
  31. kubed_mcp-0.0.1/pyproject.toml +99 -0
  32. kubed_mcp-0.0.1/setup.cfg +4 -0
  33. kubed_mcp-0.0.1/tests/test_package.py +26 -0
@@ -0,0 +1,6 @@
1
+ # Reduce incidence of needless merge conflicts on CHANGELOG.md
2
+ # The man page at
3
+ # https://mirrors.edge.kernel.org/pub/software/scm/git/docs/gitattributes.html
4
+ # suggests that this might interleave lines arbitrarily, but empirically
5
+ # it keeps added chunks contiguous
6
+ CHANGELOG.md merge=union
@@ -0,0 +1,3 @@
1
+ # Every change needs the owner's review: the agent workflows, their roles and CLAUDE.md
2
+ # decide what runs on the claude runner.
3
+ * @kferrone
@@ -0,0 +1 @@
1
+ addAssignees: author
@@ -0,0 +1,126 @@
1
+ # Copilot code review — kubed-mcp
2
+
3
+ ## Purpose & scope
4
+
5
+ You are reviewing pull requests for a **Python library**: `kubed-mcp`, imported as `kubed.mcp`, an
6
+ opinionated platform on top of FastMCP that mcp-kb and selenium-flow share. It owns how a server
7
+ serves plugins, the MCP protocol details that come with it, and extension points loaded through
8
+ Python entry points. It ships as a Python distribution on PyPI, with no image and no deployment
9
+ manifest. While it is a skeleton, most pull requests are devops and docs.
10
+
11
+ **Read these repo files first — they are the source of truth, and you should back your comments
12
+ with them:**
13
+
14
+ - **`AGENTS.md`** — the non-negotiables and the reasoning behind them.
15
+ - **`CONTRIBUTING.md`** — the layout and what CI will say about a change.
16
+
17
+ When a convention is undocumented, the sibling repos `kubed-io/mcp-kb` and `kubed-io/selenium-flow`
18
+ set the house style for CI, release flow and layout.
19
+
20
+ ## The maintainer is **Dr K**. Never write a real name.
21
+
22
+ This repository is public. The maintainer is **Dr K** in prose, commit messages, PR descriptions and
23
+ comments.
24
+
25
+ **No first name, no surname, no personal email, no personal domain, no personal GitHub handle**
26
+ outside `CODEOWNERS`. Not in a code comment, a test fixture or a transcript quoting a live instance.
27
+ A real hostname pasted in as evidence is the same leak. **Flag any real name or homelab hostname in a
28
+ diff as a blocker.**
29
+
30
+ ## The layout
31
+
32
+ | Path | Holds |
33
+ |---|---|
34
+ | `kubed/mcp/` | the library |
35
+ | `tests/` | pytest, with no network |
36
+ | `docs/` | the GitHub wiki, as a submodule |
37
+
38
+ `kubed/` is a **PEP 420 namespace package and has no `__init__.py`**, which is what lets `kubed.mcp`
39
+ install beside `kubed.mcp_kb` and `kubed.selenium_flow`. A PR that adds one is a finding.
40
+
41
+ ## Review priorities (highest first)
42
+
43
+ 1. **Public API** — servers import this package, so a renamed, retyped or removed public name is a
44
+ breaking change. It needs a **BREAKING:** changelog line and the matching change in both servers;
45
+ carrying the old shape for compatibility is not required.
46
+ 2. **Entry-point groups** — a group is an interface and its members live in other packages. A change
47
+ to a group's contract without versioning is a finding. A new group needs a real use case: an
48
+ implementation that must live in another project, or a real branch in how something is done.
49
+ 3. **Correctness** — error paths and edge cases; re-derive test expectations from the documented
50
+ behaviour, not from the current implementation.
51
+ 4. **Dead code & simplification** — unused code and imports, redundant abstractions.
52
+ 5. **Tests** — a `kubed/mcp/` change should carry a test in `tests/`.
53
+
54
+ ## Signal over volume
55
+
56
+ Fewer, higher-value comments beat exhaustive nitpicking. Noise trains the team to ignore you.
57
+
58
+ - **Worth a comment:** correctness, the public API, and the entry-point contracts — always.
59
+ - **Usually skip:** a wording tweak, a slightly stale comment, a missing type on an internal helper.
60
+ - **Verify a bug is real before flagging it.** Trace the guards in the same function and confirm the
61
+ failure path is reachable.
62
+ - **Assume the library is correct before calling something unsafe.** If FastMCP plausibly handles the
63
+ concern, assume it does unless the code shows otherwise.
64
+
65
+ ## Python conventions specific to this repo
66
+
67
+ - **Annotate the public API.** `param: str | None = None`, never `param: str = None`; no bare `dict`
68
+ or untyped `**kwargs` on a public name.
69
+ - **A glob ending in `**` is written `dir/**/*`.** Before Python 3.13 a trailing `**` matches
70
+ directories only.
71
+ - Prefer `pathlib` over `os.path`, f-strings over `%`/`.format`, and
72
+ `from __future__ import annotations` at the top of new modules.
73
+
74
+ ## Project non-negotiables — do not approve changes that break these
75
+
76
+ - **Versions come from git tags.** Never ask for a hand-written version bump; the release flow owns
77
+ versions.
78
+ - **No secret in a log, an error message or a path.**
79
+
80
+ ## CI conventions
81
+
82
+ Workflow changes are governed by
83
+ [github-workflows.instructions.md](./instructions/github-workflows.instructions.md), YAML style by
84
+ [yaml.instructions.md](./instructions/yaml.instructions.md), and Python by
85
+ [python.instructions.md](./instructions/python.instructions.md).
86
+
87
+ - **Required checks must never be path-filtered.** A path-filtered required check never reports on a
88
+ PR that misses the filter, and the PR can then never merge.
89
+ - **Every quality gate has a config file with reasons.** `.github/zizmor.yml` records *why* each rule
90
+ is relaxed. A PR that adds an ignore without a reason is a finding.
91
+ - **A draft runs no checks.**
92
+
93
+ ## Changelog entries are release notes — review them as such
94
+
95
+ `CHANGELOG.md`'s `[Unreleased]` section is handed verbatim to the release. It is worth a comment when
96
+ it is wrong, and the failure is almost always one of these:
97
+
98
+ - **A paragraph instead of a line.** Propose the one-line version; the reasoning belongs in
99
+ `AGENTS.md` or the PR. Only **BREAKING:** may stretch.
100
+ - **An entry for internal work.** CI, refactors, dependency bumps, tests and docs earn no entry; the
101
+ `no changelog` label is the intended answer.
102
+ - **An edit to a released section.** Everything below `[Unreleased]` is immutable.
103
+ - **A hand-written version heading or version bump.**
104
+
105
+ ## The agent workflows
106
+
107
+ The agent workflows run Dr K's issue → spec → plan → code → review flow on the self-hosted `claude`
108
+ runner. Each calls the workflow of the same name in kubed-io/actions, where the jobs live. A PR from
109
+ an `issue-<N>` branch with the `agent` label is the agents' work.
110
+
111
+ - **They start only on `repository_dispatch`**, which n8n sends. Don't add `issues`, `issue_comment`
112
+ or `pull_request_target` triggers.
113
+ - **`kubed-io/actions/*@main`** is first-party and has no tags; see `.github/zizmor.yml`.
114
+ - **`.issue/` is the agents' scratch** and is gitignored. Any `.issue/` file in a diff is a finding.
115
+
116
+ ## Review style
117
+
118
+ - Be specific and actionable: cite the file and line, and name the fix.
119
+ - Explain the "why" in one line.
120
+ - Stay within the diff and its blast radius.
121
+
122
+ ## What not to flag (settled)
123
+
124
+ - **Actions are pinned to release tags, not commit hashes.** A recorded decision; see `unpinned-uses`
125
+ in `.github/zizmor.yml`.
126
+ - **A terse changelog entry is correct, not lazy.** One line is the house style.
@@ -0,0 +1,59 @@
1
+ # Dependabot version updates (security updates are toggled in repo settings,
2
+ # not in this file). One entry per package manager active in the repo.
3
+ #
4
+ # House rules:
5
+ # - Weekly cadence: enough to stay current without spamming the queue.
6
+ # - Grouped minor + patch per ecosystem; majors stay separate for review.
7
+ # - A one-week cooldown so a release that gets yanked, or has its first
8
+ # post-publish advisory filed against it, is pulled before it reaches us.
9
+ # - Commit prefix is distinct per ecosystem so the merge queue reads cleanly.
10
+ #
11
+ # Docs: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference
12
+ version: 2
13
+ updates:
14
+
15
+ # GitHub Actions: keeps every `uses:` pin across workflows current.
16
+ - package-ecosystem: github-actions
17
+ directory: /
18
+ schedule:
19
+ interval: weekly
20
+ day: monday
21
+ open-pull-requests-limit: 5
22
+ labels:
23
+ - dependencies
24
+ - github-actions
25
+ # skips the pr.yml changelog gate — dependency bumps still land in release
26
+ # notes via version-bump's PR-based generation.
27
+ - no changelog
28
+ commit-message:
29
+ prefix: ci(deps)
30
+ cooldown:
31
+ # github-actions is not semver-versioned, so only default-days is valid here.
32
+ default-days: 7
33
+ groups:
34
+ actions-minor-patch:
35
+ update-types:
36
+ - minor
37
+ - patch
38
+
39
+ # Python: fastmcp is the main runtime dependency and the whole library is built on it,
40
+ # so a major bump is a real review.
41
+ - package-ecosystem: pip
42
+ directory: /
43
+ schedule:
44
+ interval: weekly
45
+ day: monday
46
+ open-pull-requests-limit: 5
47
+ labels:
48
+ - dependencies
49
+ - python
50
+ - no changelog
51
+ commit-message:
52
+ prefix: deps(pip)
53
+ cooldown:
54
+ default-days: 7
55
+ groups:
56
+ pip-minor-patch:
57
+ update-types:
58
+ - minor
59
+ - patch
@@ -0,0 +1,152 @@
1
+ ---
2
+ description: 'GitHub Actions workflow conventions for this repo'
3
+ applyTo: '.github/workflows/*.yml,.github/workflows/*.yaml,.github/actions/*/*.yml'
4
+ ---
5
+ # GitHub Actions workflow conventions
6
+
7
+ Applies to CI workflows and composite actions. YAML formatting rules come from
8
+ [yaml.instructions.md](./yaml.instructions.md); this file is the Actions-specific
9
+ review rules. These are hard conventions in this repo — flag violations.
10
+
11
+ ## Naming
12
+ - Every **job** has a `name` that summarises what it does.
13
+ - Every **step** has a `name`. Add an `id` only when a later step references its
14
+ outputs (keep ids short, lowercase, hyphenated).
15
+
16
+ ## No `${{ }}` inside `run:` scripts — bind to `env:` instead
17
+ GitHub interpolates `${{ }}` into the script *before* the shell runs — that mixes
18
+ templating with logic, is a shell-injection risk, and makes the step impossible to
19
+ run or debug outside Actions. Bind the expression to an `env:` entry on the step and
20
+ read the clean `$VAR` in bash. The step then works locally with the same env set.
21
+
22
+ ```yaml
23
+ # Bad — expression woven into the script
24
+ - name: Tag image
25
+ run: docker tag app:latest app:${{ github.sha }}
26
+
27
+ # Good — expression on env:, plain $VAR in the script (portable + injection-safe)
28
+ - name: Tag image
29
+ env:
30
+ SHA: ${{ github.sha }}
31
+ run: docker tag app:latest "app:$SHA"
32
+ ```
33
+ Prefer `env:` for static/derivable values too. This is the single most important
34
+ rule here.
35
+
36
+ ## Keep `run:` blocks pure — comment *above* the step, not inside it
37
+ Put explanatory `#` comments as YAML comments above the step so the `run:` body
38
+ stays a clean, readable script. Don't narrate inside the script.
39
+
40
+ ```yaml
41
+ # Wait for the DB to accept connections before migrating — the container reports
42
+ # ready before the socket is actually up.
43
+ - name: Wait for database
44
+ run: |
45
+ until pg_isready -h localhost; do sleep 1; done
46
+ ```
47
+
48
+ ## One function per step — don't build a mega-script
49
+ If a step does several logical things (build → sign → upload), split it into
50
+ separate `run:` steps, each doing one functional part with a clear tool and clear
51
+ inputs/outputs. Small steps are easier to read, cache, retry, and debug; a failure
52
+ points at the exact function. Pass data between them via step outputs (below).
53
+
54
+ ## `GITHUB_ENV` only for flow-wide values; otherwise use step outputs
55
+ - Write to `GITHUB_ENV` **only** when a value is genuinely useful to the whole job
56
+ (many later steps need it) — everything after it can see it, so it pollutes the
57
+ env if overused.
58
+ - When data belongs to one producer→consumer hop, isolate it with a **step output**
59
+ (`echo "key=value" >> "$GITHUB_OUTPUT"`, read as `${{ steps.<id>.outputs.key }}`)
60
+ or a **job output**. Keep the shared env small and intentional.
61
+
62
+ ## Don't guess action or tool versions — verify
63
+ LLMs (and humans) routinely pin stale majors. Before adding or bumping any
64
+ `uses:` pin, confirm the current version with the CLI, e.g.
65
+ `gh api repos/<owner>/<repo>/releases/latest --jq .tag_name`. Never assume `@vN`.
66
+
67
+ ## Other conventions
68
+ - **Provision first, act second.** Group install/setup steps up front, then a
69
+ readiness gate, then the actual work — don't stagger "install A → use A → install
70
+ B → use B".
71
+ - **Invoke scripts as `bash path/to/x.sh`**, not via the executable bit.
72
+ - **Multiline output**: use a `cat` heredoc, not many `echo`s:
73
+ ```yaml
74
+ - name: Print summary
75
+ run: |
76
+ cat <<'EOF'
77
+ line one
78
+ line two
79
+ EOF
80
+ ```
81
+ - **Secrets**: never `echo` a secret; if a value is derived from one, `::add-mask::`
82
+ it. Don't put secrets in step names or outputs.
83
+
84
+ ## Bash by default — reach for `actions/github-script` when bash is the wrong tool
85
+ Bash is the default and most steps should stay bash: it's readable, portable, and
86
+ runs the same locally. But there are jobs where bash actively gets in the way, and
87
+ forcing them into `curl | sed` is where pipelines get finicky and flaky. In those
88
+ cases use [`actions/github-script`](https://github.com/actions/github-script) —
89
+ it runs JS in the runner with an authenticated Octokit (`github`), `context`,
90
+ `core`, and `exec` already wired up.
91
+
92
+ **Use it when:**
93
+ - **The call is more than a fetch.** Anything needing real JSON handling, paging,
94
+ retries with backoff, or reading one response to build the next. `json_field() {
95
+ sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p"; }` works right up until a value
96
+ contains a quote, is nested, or is a number — and then it silently returns empty.
97
+ - **Concurrency helps.** Polling several endpoints, fanning out N requests, or
98
+ racing a timeout against a readiness check. `Promise.all` / `Promise.race` beat
99
+ backgrounded subshells and `wait`.
100
+ - **You're talking to the GitHub API.** `github.rest.*` is authenticated, typed,
101
+ and paginated (`github.paginate`) — no `curl -H "Authorization: …"`, no
102
+ hand-rolled `Link` header parsing.
103
+ - **The logic has real branching.** Once a step grows conditionals over parsed
104
+ data, JS is easier to read and to reason about than nested `if`/`case` on
105
+ string comparisons.
106
+
107
+ **Keep bash when:** running a build/test tool, a few sequential commands, simple
108
+ file wrangling, or anything a developer would want to paste into their own shell.
109
+ Don't rewrite working bash for its own sake.
110
+
111
+ **Rules when you do use it:**
112
+ - The `${{ }}` rule above still applies — **never interpolate into `script:`**.
113
+ Pass values through `env:` and read `process.env.VAR`. The injection risk is
114
+ worse here, not better: `${{ }}` lands inside a JS program.
115
+ - Return values with `core.setOutput()`; fail with `core.setFailed()` so the step
116
+ actually goes red. A thrown promise rejection that isn't awaited will not.
117
+ - Log with `core.info()` / `core.warning()`, and `core.setSecret()` anything
118
+ derived from a secret — the `::add-mask::` equivalent.
119
+ - Keep it to one function per step, same as bash. If it needs its own file, it
120
+ wants to be a real script (or a composite action), not a giant inline `script:`.
121
+
122
+ ```yaml
123
+ # Bad — bash doing JSON surgery with sed, and interpolating into the script
124
+ - name: Wait for service
125
+ run: |
126
+ for i in $(seq 1 60); do
127
+ t=$(curl -s ${{ env.URL }}/api/status | sed -n 's/.*"ready":\([^,]*\).*/\1/p')
128
+ if [ "$t" = "true" ]; then exit 0; fi
129
+ sleep 1
130
+ done
131
+ exit 1
132
+
133
+ # Good — real JSON, a real timeout, values via env:
134
+ - name: Wait for service
135
+ uses: actions/github-script@v9
136
+ env:
137
+ URL: ${{ env.URL }}
138
+ with:
139
+ script: |
140
+ const deadline = Date.now() + 60_000;
141
+ while (Date.now() < deadline) {
142
+ try {
143
+ const res = await fetch(`${process.env.URL}/api/status`);
144
+ if (res.ok && (await res.json()).ready) {
145
+ core.info('service is ready');
146
+ return;
147
+ }
148
+ } catch { /* not up yet — keep polling */ }
149
+ await new Promise(r => setTimeout(r, 1000));
150
+ }
151
+ core.setFailed('service did not become ready in 60s');
152
+ ```
@@ -0,0 +1,54 @@
1
+ ---
2
+ description: 'Python conventions for this repo'
3
+ applyTo: 'kubed/**/*.py,scripts/**/*.py,tests/**/*.py'
4
+ ---
5
+ # Python conventions
6
+
7
+ Applies to every `.py` file here. Cross-cutting review priorities are in
8
+ [copilot-instructions.md](../copilot-instructions.md); this file is the
9
+ language-specific rules. These are hard conventions — flag violations.
10
+
11
+ ## The supported range is whatever `pyproject.toml` declares
12
+
13
+ `requires-python` is the floor, and the test matrix sweeps the whole range. A newer syntax or
14
+ stdlib feature is a **build break on the oldest supported interpreter**, not a style question.
15
+ Raising the floor is its own PR, deliberately, never a side effect.
16
+
17
+ - A glob ending in `**` matches directories only before 3.13, so in code always write
18
+ `dir/**/*`.
19
+ - `X | Y` in an annotation is fine **because every module starts with
20
+ `from __future__ import annotations`**. Used at runtime — `isinstance(x, A | B)`,
21
+ a `TypeAlias` value, a pydantic field evaluated eagerly — it needs care.
22
+
23
+ ## This is a library: the public API is a contract
24
+
25
+ Servers install this package and import it, so a name that is public is a name somebody depends on.
26
+
27
+ - Annotate every public parameter and return. `param: str | None = None`, never
28
+ `param: str = None`; a bare `dict` or `**kwargs` is a finding.
29
+ - Prefer a `Literal[...]` over `str` when the set of values is closed.
30
+ - Renaming, retyping or removing a public name is a breaking change and needs the changelog's
31
+ **BREAKING:** line. Adding an optional argument is safe.
32
+ - Entry-point groups are interfaces. Never change a group's contract without versioning it.
33
+ - Docstrings on public names are what an integrator reads. Write them for that reader.
34
+
35
+ ## Style
36
+
37
+ - `from __future__ import annotations` at the top of every new module.
38
+ - `pathlib` over `os.path`; f-strings over `%` or `.format`.
39
+ - Module docstrings explain *why the module exists*, not a restatement of the names inside it.
40
+ - ruff is the linter and the gate, run as `ruff check .` over the whole checkout, tests included.
41
+
42
+ ## Errors
43
+
44
+ - Never swallow an exception to return a falsy value. A silent empty result is
45
+ indistinguishable from a real one.
46
+ - Never put a token, a URL with credentials, or a full request body into an exception message or a
47
+ log line.
48
+
49
+ ## Tests
50
+
51
+ - `tests/` runs with no network. A test that reaches out is an integration test and is marked
52
+ `@pytest.mark.integration`.
53
+ - Test through the real entry point, not only the helper.
54
+ - `asyncio_mode = "auto"`, so an `async def test_` needs no decorator.
@@ -0,0 +1,28 @@
1
+ ---
2
+ description: 'YAML formatting conventions for this repo'
3
+ applyTo: '**/*.yaml,**/*.yml'
4
+ ---
5
+ # YAML conventions
6
+
7
+ Formatting rules for every YAML file in this repo (CI workflows, dependabot, the zizmor config, …).
8
+ Cross-cutting review rules are in `.github/copilot-instructions.md`.
9
+
10
+ ## Formatting
11
+ - 2-space indentation, spaces never tabs; consistent throughout the file.
12
+ - **Sequences align with their parent key** (block style, not indented two extra
13
+ spaces):
14
+ ```yaml
15
+ fruits:
16
+ - apple
17
+ - banana
18
+ - cherry
19
+ ```
20
+ - Lowercase keys; separate words with `_` or `-`.
21
+ - Don't quote strings unless they contain special characters or start with a number
22
+ (e.g. a value like `"true"`, `"3.0"`, or one with a `:` needs quotes).
23
+ - A `description` over 100 characters is a `|` block wrapped at 100 columns, never one long line.
24
+ - Use `#` comments to explain non-obvious sections.
25
+
26
+ ## Review focus
27
+ - Flag tabs, inconsistent indentation, and sequences indented under their key.
28
+ - Flag needless quoting and non-lowercase keys.
@@ -0,0 +1,97 @@
1
+ name: 🧹 Lint
2
+
3
+ # The static gates, kept out of test.yml so a red here names the thing that is wrong
4
+ # instead of burying it in a test run. Two independent jobs, both fast, in parallel:
5
+ #
6
+ # Ruff ruff over the whole checkout, tests included
7
+ # Dependency Audit pip-audit over the resolved RUNTIME dependency set
8
+ #
9
+ # The scanners, whose findings go to code scanning, are quality.yml.
10
+
11
+ on:
12
+ # pull requests: pr.yml calls this, with every other gate, so one collector sees them all
13
+ push:
14
+ branches: [main]
15
+ workflow_dispatch:
16
+ workflow_call: {}
17
+
18
+ permissions:
19
+ contents: read
20
+
21
+ jobs:
22
+
23
+ ruff:
24
+ name: Ruff
25
+ runs-on: ubuntu-26.04
26
+ permissions:
27
+ contents: read
28
+ steps:
29
+
30
+ - name: Checkout
31
+ uses: actions/checkout@v7
32
+ with:
33
+ persist-credentials: false
34
+
35
+ - name: Setup Python
36
+ uses: actions/setup-python@v7
37
+ with:
38
+ python-version: '3.14'
39
+
40
+ # ruff reads its config from pyproject.toml and needs nothing else installed.
41
+ - name: Install Ruff
42
+ run: pip install ruff
43
+
44
+ # No paths: the ruff config covers the whole checkout, so naming directories here
45
+ # would be a second list to keep in sync with it.
46
+ - name: Lint
47
+ run: ruff check --output-format=github .
48
+
49
+ # ---------------------------------------------------------------------------
50
+ # Known-vulnerability audit of what a user's install actually pulls in.
51
+ # ---------------------------------------------------------------------------
52
+ deps:
53
+ name: Dependency Audit
54
+ runs-on: ubuntu-26.04
55
+ permissions:
56
+ contents: read
57
+ steps:
58
+
59
+ - name: Checkout
60
+ uses: actions/checkout@v7
61
+ with:
62
+ # setuptools_scm resolves the version from history at install time.
63
+ fetch-depth: 0
64
+ persist-credentials: false
65
+
66
+ - name: Setup Python
67
+ uses: actions/setup-python@v7
68
+ with:
69
+ python-version: '3.14'
70
+ cache: pip
71
+ cache-dependency-path: pyproject.toml
72
+
73
+ # Runtime only. The test extra is deliberately NOT installed here: ruff and
74
+ # pytest never reach a user, and an advisory against a test-only tool that
75
+ # stops a release is noise, not security.
76
+ - name: Install Runtime Dependencies
77
+ run: pip install --editable .
78
+
79
+ # --exclude-editable drops kubed-mcp itself: pip-audit would look up this
80
+ # checkout's dev version on PyPI and fail to resolve it, which reads like a
81
+ # broken audit rather than an unreleased version.
82
+ - name: Freeze Runtime Dependencies
83
+ run: pip freeze --exclude-editable > requirements.txt
84
+
85
+ - name: Audit Dependencies
86
+ uses: pypa/gh-action-pip-audit@v1.1.0
87
+ with:
88
+ inputs: requirements.txt
89
+ summary: true
90
+
91
+ - name: Upload Resolved Dependencies
92
+ if: always()
93
+ uses: actions/upload-artifact@v7
94
+ with:
95
+ name: requirements-lock
96
+ path: requirements.txt
97
+ if-no-files-found: error
@@ -0,0 +1,143 @@
1
+ name: 🗿 Package
2
+
3
+ # Builds the Python distribution (sdist + wheel) and nothing else, then saves it
4
+ # as a GHA artifact. It never bumps versions, tags, or publishes anywhere:
5
+ #
6
+ # pull_request the gate, called by pr.yml — proves the wheel still builds and installs
7
+ # push: main same, so the badge tracks trunk
8
+ # workflow_dispatch package an arbitrary ref
9
+ # workflow_call publish.yml passes the release tag, so the distribution is
10
+ # built from exactly the released commit; its pypi and
11
+ # release jobs upload this artifact, byte for byte
12
+ #
13
+ # The version is not an input: setuptools_scm derives it from git.
14
+
15
+ on:
16
+ # pull requests: pr.yml calls this, with every other check, so one collector sees them all
17
+ # (with no path filter: a required check that never reports blocks a PR forever)
18
+ push:
19
+ branches: [main]
20
+ workflow_dispatch: {}
21
+ workflow_call:
22
+ inputs:
23
+ tag:
24
+ description: Git tag to check out and build — empty = the caller's ref
25
+ type: string
26
+ required: false
27
+ default: ''
28
+ outputs:
29
+ version:
30
+ description: Version built, as setuptools_scm resolved it from git
31
+ value: ${{ jobs.package.outputs.version }}
32
+ package:
33
+ description: Name of the uploaded artifact holding the sdist + wheel
34
+ value: ${{ jobs.package.outputs.package }}
35
+ sdist:
36
+ description: sdist file name
37
+ value: ${{ jobs.package.outputs.sdist }}
38
+ wheel:
39
+ description: wheel file name
40
+ value: ${{ jobs.package.outputs.wheel }}
41
+
42
+ permissions:
43
+ contents: read
44
+
45
+ jobs:
46
+
47
+ package:
48
+ name: Package
49
+ runs-on: ubuntu-26.04
50
+ permissions:
51
+ contents: read
52
+ outputs:
53
+ version: ${{ steps.version.outputs.version }}
54
+ package: ${{ steps.version.outputs.package }}
55
+ sdist: ${{ steps.files.outputs.sdist }}
56
+ wheel: ${{ steps.files.outputs.wheel }}
57
+ steps:
58
+
59
+ - name: Checkout
60
+ uses: actions/checkout@v7
61
+ with:
62
+ ref: ${{ inputs.tag }}
63
+ # A shallow clone silently yields a 0.1.devN version instead of the tag.
64
+ fetch-depth: 0
65
+ persist-credentials: false
66
+
67
+ - name: Setup Python
68
+ uses: actions/setup-python@v7
69
+ with:
70
+ python-version: '3.14'
71
+ cache: pip
72
+ cache-dependency-path: pyproject.toml
73
+
74
+ - name: Install Build Dependencies
75
+ run: pip install ".[build]"
76
+
77
+ # Resolve the version BEFORE building, so a wrong one is caught here rather
78
+ # than discovered as a confusingly-named file three steps later.
79
+ - name: Resolve Version
80
+ id: version
81
+ run: |
82
+ version="$(python -m setuptools_scm)"
83
+ echo "Building version: $version"
84
+ {
85
+ echo "version=$version"
86
+ echo "package=kubed_mcp-${version}"
87
+ } >> "$GITHUB_OUTPUT"
88
+
89
+ - name: Build
90
+ run: python -m build
91
+
92
+ # Names come from the files on disk: a wheel carries a Python tag the
93
+ # version string does not.
94
+ - name: Resolve Artifact Names
95
+ id: files
96
+ run: |
97
+ {
98
+ echo "sdist=$(basename dist/*.tar.gz)"
99
+ echo "wheel=$(basename dist/*.whl)"
100
+ } >> "$GITHUB_OUTPUT"
101
+ ls -l dist
102
+
103
+ - name: Check Distribution Metadata
104
+ run: twine check --strict dist/*
105
+
106
+ # A clean venv proves the wheel imports as kubed.mcp, reports the version it was
107
+ # built as, and left `kubed` a namespace: a kubed/__init__.py in the wheel would
108
+ # shadow every other kubed.* distribution installed beside it.
109
+ - name: Verify the Wheel Installs
110
+ env:
111
+ VERSION: ${{ steps.version.outputs.version }}
112
+ run: |
113
+ python -m venv /tmp/verify
114
+ /tmp/verify/bin/pip install --quiet "$(echo dist/*.whl)"
115
+ /tmp/verify/bin/python - <<'EOF'
116
+ import os
117
+ import kubed
118
+ import kubed.mcp
119
+ assert getattr(kubed, "__file__", None) is None, "kubed is not a namespace package"
120
+ assert kubed.mcp.__version__ == os.environ["VERSION"], kubed.mcp.__version__
121
+ print("kubed.mcp", kubed.mcp.__version__)
122
+ EOF
123
+
124
+ - name: Upload Package
125
+ uses: actions/upload-artifact@v7
126
+ with:
127
+ name: ${{ steps.version.outputs.package }}
128
+ path: dist/
129
+ if-no-files-found: error
130
+
131
+ - name: Summary
132
+ env:
133
+ VERSION: ${{ steps.version.outputs.version }}
134
+ SDIST: ${{ steps.files.outputs.sdist }}
135
+ WHEEL: ${{ steps.files.outputs.wheel }}
136
+ run: |
137
+ cat >> "$GITHUB_STEP_SUMMARY" <<EOF
138
+ ## Package
139
+
140
+ - **Version**: \`${VERSION}\`
141
+ - **sdist**: \`${SDIST}\`
142
+ - **wheel**: \`${WHEEL}\`
143
+ EOF