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.
- kubed_mcp-0.0.1/.gitattributes +6 -0
- kubed_mcp-0.0.1/.github/CODEOWNERS +3 -0
- kubed_mcp-0.0.1/.github/assign.yml +1 -0
- kubed_mcp-0.0.1/.github/copilot-instructions.md +126 -0
- kubed_mcp-0.0.1/.github/dependabot.yml +59 -0
- kubed_mcp-0.0.1/.github/instructions/github-workflows.instructions.md +152 -0
- kubed_mcp-0.0.1/.github/instructions/python.instructions.md +54 -0
- kubed_mcp-0.0.1/.github/instructions/yaml.instructions.md +28 -0
- kubed_mcp-0.0.1/.github/workflows/lint.yml +97 -0
- kubed_mcp-0.0.1/.github/workflows/package.yml +143 -0
- kubed_mcp-0.0.1/.github/workflows/pr.yml +118 -0
- kubed_mcp-0.0.1/.github/workflows/publish.yml +282 -0
- kubed_mcp-0.0.1/.github/workflows/quality.yml +95 -0
- kubed_mcp-0.0.1/.github/workflows/test.yml +132 -0
- kubed_mcp-0.0.1/.github/zizmor.yml +73 -0
- kubed_mcp-0.0.1/.gitignore +43 -0
- kubed_mcp-0.0.1/AGENTS.md +59 -0
- kubed_mcp-0.0.1/CHANGELOG.md +32 -0
- kubed_mcp-0.0.1/CONTRIBUTING.md +74 -0
- kubed_mcp-0.0.1/LICENSE +21 -0
- kubed_mcp-0.0.1/PKG-INFO +79 -0
- kubed_mcp-0.0.1/README.md +44 -0
- kubed_mcp-0.0.1/kubed/mcp/__init__.py +12 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/PKG-INFO +79 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/SOURCES.txt +31 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/dependency_links.txt +1 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/requires.txt +12 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/scm_file_list.json +28 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/scm_version.json +8 -0
- kubed_mcp-0.0.1/kubed_mcp.egg-info/top_level.txt +1 -0
- kubed_mcp-0.0.1/pyproject.toml +99 -0
- kubed_mcp-0.0.1/setup.cfg +4 -0
- 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 @@
|
|
|
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
|