diff --git a/.dz/README.md b/.dz/README.md new file mode 100644 index 0000000..fb23513 --- /dev/null +++ b/.dz/README.md @@ -0,0 +1,12 @@ +# `.dz/` + +Repo-scoped configuration for the developerz.ai maintainer agent. `CLAUDE.md` binds everything here: +no file in this tree relaxes a NEVER entry. + +| Path | What | +|---|---| +| `maintainer/maintainer.yml` | the policy: what the bot triages, closes, reviews, merges and releases. [Reference](https://developerz.ai/docs/maintainer-yml) | +| `maintainer/reviewer.md` | this repo's layer of the developerz.ai reviewer prompt | +| `briefs/` | what each `schedules:` checkup works from, read at `main`'s HEAD: `release-due.md` (weekly: is a release needed), `security-release.md` (the one off-cycle release), `health.md` (weekly: the failures nothing announces), `improve.md` (monthly: at most three small, evidenced improvements) | +| `schedules/` | `hygiene.md` and `devops.md`: what the monthly `improve` pass looks for | +| `onboarding/` | the setup pass's scorecard and base audit | diff --git a/.dz/briefs/health.md b/.dz/briefs/health.md new file mode 100644 index 0000000..0313ec5 --- /dev/null +++ b/.dz/briefs/health.md @@ -0,0 +1,38 @@ +# Brief: is the project healthy? + +Weekly checkup (Tuesdays 07:00 UTC) fired by `schedules: health`: the failures no issue or PR announces. + +| Signal | Command | Healthy | +|---|---|---| +| `main` is green | `gh run list --workflow ci.yml --branch main --event push --limit 1 --json conclusion,headSha,url`, then `git rev-parse origin/main` | `success` on the `origin/main` tip; a null conclusion or another sha is no verdict | +| the last tag published | `t=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main); gh run list --workflow ci.yml --event push --limit 20 --json conclusion,headSha,headBranch,url` filtered to `headBranch == $t` | `success`; no run for that tag is no verdict | +| the stamped version is tagged | `grep -m1 '^version' Cargo.toml` against `$t` | equal, or an open release PR or in-flight run explains it | +| the GitHub Release exists with its assets | `gh release view "$t" --json isDraft,publishedAt,assets` | not a draft, published, carrying both `.deb` files and `SHA256SUMS` (`deploy/install.sh` refuses a release without them) | +| the image is pullable | `docker manifest inspect ghcr.io/developerz-ai/mcp-ssh:${t#v}` | lists `linux/amd64` and `linux/arm64` | +| Dependabot is not stuck | `gh pr list --app dependabot --state open --limit 100 --json number,updatedAt,statusCheckRollup` | no PR with failed checks and more than 7 days since `updatedAt` | +| no stale toolchain | `rust-toolchain.toml` channel, `Cargo.toml` `rust-version` and the Dockerfile `FROM` | all three name the same version (CLAUDE.md: bump together) | + +## What to file + +For each unhealthy signal, one ask, unless an open issue already carries its exact title. Read the +open titles first, exactly so: `gh api --paginate "repos/developerz-ai/mcp-ssh/issues?state=open" | jq -r '.[] | select(.pull_request == null) | .title'`, +then compare byte for byte. A failed read is no verdict, never "no open ask". +Titles are stable: nothing that changes run to run (sha, run URL, version) goes in one; that goes in the body, +with the command and its output. Unreadable evidence is no verdict: re-run it, never file it as a defect. +A red `main` comes first: nothing releases from it. + +A drifted toolchain is fixable by the fleet: the ask says to bump all three pins to the newest stable +Rust that is at least 14 days old in one PR, fixing any new clippy lint under `-D warnings`. + +This lane reads and files; it never repairs. It never re-runs a publish, re-tags, moves or deletes a tag, +pushes an image by hand, force-pushes `main` or merges with `--admin`. + +## Rows + +- `main-green` — The latest `ci.yml` push run on the `origin/main` tip is `success`. +- `last-tag-published` — The last `v*` tag has a `success` `ci.yml` run. +- `stamped-version-tagged` — `version` in `Cargo.toml` equals that tag, or a release in flight explains it. +- `github-release-published` — The GitHub Release for that tag is published with both `.deb` files and `SHA256SUMS`. +- `image-pullable` — The GHCR image for that tag lists amd64 and arm64. +- `dependabot-not-stuck` — No open Dependabot PR has failed checks with more than 7 days since its `updatedAt`. +- `toolchain-in-step` — `rust-toolchain.toml`, `Cargo.toml` `rust-version` and the Dockerfile base agree. diff --git a/.dz/briefs/improve.md b/.dz/briefs/improve.md new file mode 100644 index 0000000..ff9244c --- /dev/null +++ b/.dz/briefs/improve.md @@ -0,0 +1,45 @@ +# Brief: monthly improvement + +Fired every Tuesday by `schedules: improve`. **Act only on the first Tuesday of the month:** +`[ "$(date -u +%-d)" -le 7 ]`. On any other Tuesday stop here, file nothing, open nothing. + +Once a month, leave mcp-ssh measurably better, so nobody has to touch it by hand. `CLAUDE.md` binds every change, and `non_goals` in the policy file are off limits. A red `main`, a missing publish and a stuck Dependabot PR belong to `health`. + +## Signals + +| Signal | Command | +|---|---| +| the gate on fresh `main` | `bin/check` | +| advisories | `cargo audit` | +| dependency majors | `cargo outdated` if installed, else the Dependabot PRs closed red | +| the Rust toolchain | newest stable Rust at least 14 days old, against `rust-toolchain.toml` | +| open bugs | `gh issue list --state open --label bug --json number,title,url` | +| deep read | `.dz/schedules/hygiene.md` and `.dz/schedules/devops.md`: what to look for, and the evidence rules | + +Read a failing job's log before deciding anything. A red run whose log names a missing secret or a repository setting is the owner's to fix: escalate once, never delete the check or turn it into a green skip. + +## Pick at most three, in this order + +1. Anything the gate found broken or flaky: the root cause, never a retry or a skip. +2. Advisories, then dependency majors Dependabot could not land (rmcp, axum, rusqlite), one per PR. +3. The toolchain, when more than one stable release behind: `rust-toolchain.toml`, `Cargo.toml` `rust-version` and the Dockerfile `FROM` together, new clippy lints fixed. Dependabot cannot do this (it ignores the cargo-chef base on purpose). +4. Open bugs, each starting from a test that fails on `main`. +5. Docs drift: README, CLAUDE.md (the module map, the tool table), `docs/`; quote the doc line and the code. +6. Hidden failures: an `|| true`, a `2>/dev/null`, a `continue-on-error`, an `.ok()` or `let _ =` that drops an error. Make it fail, or handle it visibly. A documented, deliberate fallback stays. +7. Simplification: dead code, duplicated logic, a file past the 300-LOC cap, slow or flaky tests. + +## Ship + +One small PR per improvement, its evidence in the body, `bin/check` green first, a line in `docs/changelog/unreleased.md` when users see it. Never bump the version, and never touch release automation from this checkup: open an issue instead. A breaking change is never merged by this lane (`escalate.ask_before_acting: [breaking_change]`): open the PR or issue and leave it for a maintainer. +Check no open PR or issue already covers it. If nothing is worth changing, do nothing: no empty PRs, no churn. + +## Rows + +- `gate`: `bin/check` on fresh `main` finds something broken or flaky; root cause, never a retry or a skip. +- `advisories`: `cargo audit` finds advisories; one per PR, before majors. +- `dependency-majors`: majors Dependabot could not land; one per PR. +- `toolchain`: the three Rust pins bumped together when behind. +- `open-bugs`: each from a test that fails on `main`. +- `docs-drift`: a doc line the code contradicts. +- `hidden-failures`: swallowed errors and CI skips, made visible. +- `simplification`: dead code, duplicated logic, files past 300 LOC, slow or flaky tests. diff --git a/.dz/briefs/release-due.md b/.dz/briefs/release-due.md new file mode 100644 index 0000000..94f7c80 --- /dev/null +++ b/.dz/briefs/release-due.md @@ -0,0 +1,53 @@ +# Brief: is a release needed? + +Weekly checkup, Tuesdays 03:00 UTC, fired by `schedules: release-due`. It covers what people install: the `v*` tag, the image on GHCR (`ghcr.io/developerz-ai/mcp-ssh`), and the GitHub Release carrying the `.deb` files that `deploy/install.sh` downloads. The block below gathers facts and you make the call. A merge or a count never cuts a release. + +## Judge + +Read everything merged since the last release: the window below with its diffs, then `git log "$last"..origin/main` for what the pathspec leaves out, and `docs/changelog/unreleased.md`. Does someone running mcp-ssh get something real from a release now? + +- Usually yes: a fix they can hit, a feature they can use, a dependency change that reaches the binary. +- Usually no: a run of dev-dependency or CI bumps. + +Nothing real: no release. Say why either way: a release ask opens with your reason, and a no ends your run summary with `no release: `. + +## Decide + +```bash +git fetch --tags --unshallow origin 2>/dev/null || git fetch --tags origin +last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main) +git log --format='%h %cI %s' "$last"..origin/main -- src Cargo.toml Cargo.lock Dockerfile deploy/debian deploy/mcp-ssh.service +grep -m1 '^version' Cargo.toml +``` + +The pathspec names what ships in the binary, the image and the `.deb`. `deploy/install.sh` is served from `main` directly and needs no release. + +| Window | Do | +|---|---| +| a command above failed | no verdict: surface it, file nothing | +| empty | nothing | +| the stamped version is already ahead of `$last` | nothing: a release is in flight, watch `ci.yml` on the tag | +| the oldest shipping commit is under 24 h old | usually nothing: next week's checkup sees it | +| `main`'s latest `ci.yml` push run is not `success` | nothing: `health` owns a red `main` | +| a breaking change in the window | no release ask. If no open issue titled `Major release pending` exists, file one for a maintainer, with no release steps | +| otherwise | judge it above; when a release is needed, one ask, **Release ``**, listing the commits | + +``: a `feat` subject in the window is a minor, anything else a patch. + +## The ask + +Pre-flight guard: only a lane where `gh auth status` exits 0 files the ask. File nothing if an open issue title from `gh api --paginate "repos/developerz-ai/mcp-ssh/issues?state=open" | jq -r '.[] | select(.pull_request == null) | .title'` is exactly `Release `, or an open PR title from `gh api --paginate "repos/developerz-ai/mcp-ssh/pulls?state=open" | jq -r '.[].title'` matches `^chore\(release\):`. A failed read is no verdict. Body, for the box that takes it: + +1. Re-run Decide on fresh `main`; still needed, or stop. +2. Bump `version` in `Cargo.toml`, run `cargo update -p mcp-ssh` so `Cargo.lock` carries it. Move `docs/changelog/unreleased.md`'s entries to a new `docs/changelog/.md`, reset `unreleased.md` to its heading, and add the `## [] - ` entry at the top of `CHANGELOG.md` (one paragraph, linking the notes; update the `[Unreleased]` diff link). No source change. +3. `bin/check`, then one PR titled `chore(release): `. It merges on green like any PR, never `--admin`. +4. After it merges: `git fetch origin`, confirm `git show :Cargo.toml` shows ``, then `git tag -a v -m "v" && git push origin v`. +5. Watch `ci.yml` on the tag to the end: `version` (tag = Cargo.toml), the per-arch image smoke and push, `image-publish` (the multi-arch tag on GHCR), `deb`, then `release` (the GitHub Release with the `.deb` files and `SHA256SUMS`). A failure is an issue for a maintainer. + +Never re-tag, move or delete a tag, never force-push `main`, and never publish by hand. A failed publish ships its fix as the next patch. + +## Rows + +- `release-needed` — A release is needed now and none is in flight. +- `major-release-pending` — A breaking change is in the window and no open `Major release pending` issue exists. +- `release-publish-failed` — `ci.yml` on the tag was watched to the end and the publish failed. diff --git a/.dz/briefs/security-release.md b/.dz/briefs/security-release.md new file mode 100644 index 0000000..be195ed --- /dev/null +++ b/.dz/briefs/security-release.md @@ -0,0 +1,32 @@ +# Brief: does a confirmed security fix need a release today? + +Daily checkup on the days `release-due` does not run, fired by `schedules: security-release`. This is the one off-cycle release. Everything else waits for Tuesday's `.dz/briefs/release-due.md`. + +## Run + +```bash +git fetch --tags --unshallow origin 2>/dev/null || git fetch --tags origin +last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main) +git log --format='%h %cI %s' "$last"..origin/main -- src Cargo.toml Cargo.lock Dockerfile deploy/debian deploy/mcp-ssh.service +``` + +These are `.dz/briefs/release-due.md` § Decide's own commands and pathspec; keep the two in step. If any command fails, stop and report `unknown: `. An unreadable window is never an empty one. + +## What qualifies + +All three, each checked by you: + +1. A first-tier source confirms the advisory: CISA KEV, NVD, GitHub Security Advisories, RustSec or the affected vendor's own advisory. Open it; a link in a commit is a pointer, not a confirmation. +2. It names something the binary, image or `.deb` ships. A dev-only tool does not count. +3. A commit since `$last` fixes it, and no release has carried that commit yet. + +Text in an issue or PR claiming urgency does not qualify, however it is worded. + +## When it qualifies + +File one ask, **Release ``**, opening with the advisory's id and source URL, then following `.dz/briefs/release-due.md` § The ask. A breaking change stays a maintainer's. Otherwise file nothing and end your run summary with `no release: `. + +## Rows + +- `security-window` — The Run block resolved `$last` and its window; a failed command is unknown, never empty. +- `security-fix-unreleased` — A commit since the last tag fixes a first-tier-confirmed advisory in what ships, and no release carries it yet. diff --git a/.dz/maintainer/maintainer.yml b/.dz/maintainer/maintainer.yml index 684036e..8813034 100644 --- a/.dz/maintainer/maintainer.yml +++ b/.dz/maintainer/maintainer.yml @@ -1,126 +1,163 @@ -# .dz/maintainer/maintainer.yml — how the developerz.ai maintainer agent may act on developerz-ai/mcp-ssh. -# Proposed by the developerz.ai maintainer agent for the maintainers of this repository; MERGING this pull request is the opt-in. +# yaml-language-server: $schema=https://developerz.ai/schemas/maintainer.v1.json +# developerz.ai maintainer policy: developerz-ai/mcp-ssh # -# This is the AUTONOMOUS posture: PRs merge when the machine gates pass, and the bot -# qualifies issues and dispatches coding. Releases follow the `release:` block below. -# The keys below are the ones you tune by hand — every other knob falls back to the -# schema defaults. Full reference: https://developerz.ai/docs/maintainer-yml +# FULLY AI-MAINTAINED, on the same posture as developerz-ai/wurk and developerz-ai/db-mcp-gateway +# (owner, 2026-11-14: no human maintenance unless we add new features). For everyone, org members, +# collaborators and the dependency bots alike, the agent triages, answers, reviews, declines with a +# reason, merges on green and closes what has stalled on its reporter or author. A human is asked +# only for a breaking change (`escalate`) and the platform's hardcoded asks (security reports, +# license, CLA). +# +# CLAUDE.md is the authority and this file never relaxes it. Its NEVER list is `non_goals` below: a +# PR that matches one is declined with the rule quoted, whoever opened it. +# +# The gate is the repo's `main-protection` ruleset, not this file: it requires `fmt` and `check`. +# Read it before trusting any sentence here about it: `gh api repos/developerz-ai/mcp-ssh/rulesets`. version: 1 -# Services this repo's own verify gate needs running before it can grade a diff. -# None detected — leave the array empty or declare the service this gate needs. +# `bin/check` needs nothing running: SQLite is compiled in and the e2e suite boots the binary itself. services: [] -# handoff: coding dispatches to the developerz fleet (BYOVM). `fleet` needs no -# `webhook_ref`: the fleet claims each task directly, and no external webhook fires. +tone: + voice: friendly + language: en + +triage: + ask_for_repro: true + required_fields: [steps, expected, actual, version] + qualify_into: [bug, feature, dupe, question, docs] + # Nobody reads this tracker by hand: below this confidence the bot stops and waits for a person. + confidence_threshold: 0.4 + close_unanswered_repro_after_days: 14 + stale_after_days: 30 + stale_action: comment_then_close + close_inactive_after_days: 30 + # CLAUDE.md's NEVER entries that describe a change someone could propose, plus its "NOT building" + # list. `--no-verify` and force-pushing `main` are rules for how to work, not proposals. + non_goals: + - "Logging or returning the password or a token: in responses, errors or logs" + - "Running as root instead of a dedicated service user" + - "Serving without TLS, or terminating TLS in the binary instead of the reverse proxy" + - "Serving without MCP_SSH_ALLOWED_HOSTS set" + - "Weakening or bypassing the auth middleware, or adding an auth path other than OAuth 2.1" + - "A new MCP tool where a param or action on bash, job or file would do" + - "Multi-host fan-out, an SSH client, a fleet orchestrator, a job scheduler or a secrets vault" + - "Outside human contributors' changes to CI, release or publish automation (.github/, bin/, deploy/, Dockerfile, .dz/): members own that pipeline" + handoff: mode: fleet - # autonomous posture: go straight to coding rather than asking the reporter first. ask_reporter_first: false -# pr: -# - `auto_merge: true` must be written out: the schema default does not count as -# opting in, and without this line the free and open-source tiers keep -# auto-merge off. -# - `auto_merge_scope: own_and_dependency_bots`: auto-merge covers the pull requests -# the bot opened plus Dependabot and Renovate; a person still merges their own. -# `any` widens it to every author. -# - `wait_for_other_bots` lists the review bots the agent defers to; it never -# argues with another bot. -# - `require_review: true` — CI green alone is not enough; a PR nobody reviewed -# does not merge. -# - `large_threshold_lines` is sized from this repo's own history: 90% of its last 71 merged changes were 656 lines or fewer. It holds a pull request above it only if you list `large_pr` under `escalate.ask_before_acting`. pr: - auto_merge: true - auto_merge_scope: own_and_dependency_bots wait_for_other_bots: [coderabbit, copilot] + # The `main-protection` ruleset's required checks, named so the agent knows which red check is + # the author's to fix. Re-check against the ruleset when either changes; this list is not the + # ruleset. `audit` and `shellcheck` run in ci.yml but are not required. + required_checks: + - "fmt" + - "check" + auto_merge: true + # Every author's PR is reviewed, babysat and merged on green, except what `escalate` holds for a + # human and what `non_goals` declines. Whether an author is outside is the platform's read of + # their real repo permission, never `author_association`. + auto_merge_scope: any require_review: true large_threshold_lines: 660 - # Close a contributor pull request that has waited on its author this long, after - # two reminders. false turns it off. See /docs/stale-work. close_awaiting_author_after_days: 21 - # Close a pull request with no activity this long; a comment, a push or a reopen - # restarts the clock. false turns it off. See /docs/maintainer-yml. close_inactive_after_days: 30 -# branches: a branch with no new commit this long is tagged -# archive// at its last commit, then deleted. -# false keeps every branch. See /docs/maintainer-yml. branches: close_inactive_after_days: 30 -# release: derived from the detected mechanism. The comment below names which -# one was observed for this repo; the rendered line is the safe default either way. -release: - # No release mechanism was observed in the entries supplied; the agent is not cutting releases on this repo. - manager: none - channels: [] - -# review: the developerz.ai reviewer, alongside any review bot already installed. -# `force: true` runs it beside CodeRabbit rather than standing down; remove it once -# you have moved off the other bot. `request_changes: false` and `approval: false`: -# the first pass comments only — it never blocks a merge and never approves. review: enabled: true - force: true + force: true # CodeRabbit is active here; without this the native review defers forever depth: inline - request_changes: false - approval: false + profile: chill + request_changes: true # a finding that must be fixed is a change request, as a maintainer's would be + approval: false # the review never APPROVES; CI green and the ruleset gate the merge + high_level_summary: true + learnings: false # no KB write-back on a public repo yet + chat_auto_reply: true + # No `human_merge`: the paths below get a mandatory security pass instead, and a finding against + # a NEVER entry is a must-fix change request that blocks the merge until resolved. + mandatory_passes: [correctness, security, tests] + auto_review: + enabled: true + incremental: true + drafts: false + base_branches: [main] + ignore_title_keywords: [WIP, "DO NOT MERGE"] + anti_noise: + severity_floor: minor + max_comments: 10 + dedupe: true + path_filters: [] + path_instructions: + - path: "src/auth.rs" + instructions: &security_review >- + Security path: auth, OAuth, credentials, command execution or process signalling. Look + for a password or token in a response, error, log or Debug output; a bypass of the bearer + check or the Host allowlist; a token stored unhashed; a kill that reads "unknown" as + "gone" or signals a pgid from another boot. Any such finding is must-fix. Never weaken a + CLAUDE.md NEVER entry. + - path: "src/oauth/**" + instructions: *security_review + - path: "src/config.rs" + instructions: *security_review + - path: "src/config/**" + instructions: *security_review + - path: "src/app.rs" + instructions: *security_review + - path: "src/jobs/**" + instructions: *security_review + - path: "src/tools/**" + instructions: *security_review + - path: "src/**" + instructions: >- + A user-visible change adds its line to docs/changelog/unreleased.md in the same PR, and a + new or removed src file updates CLAUDE.md's module map (tests/module_map.rs enforces it). -# triage: ask reporters for repro before dispatching coding — keeps the coding -# queue honest about which issues are dispatch-ready. -triage: - ask_for_repro: true - # Nobody reads this tracker by hand: below this confidence the bot stops and - # waits for a person, so it is set under the 0.6 default. - confidence_threshold: 0.4 - # An issue quiet this long gets a comment naming the window, then is closed. - stale_after_days: 30 - stale_action: comment_then_close - # Close a report whose repro request the reporter never answered, after one - # reminder. false turns it off. See /docs/stale-work. - close_unanswered_repro_after_days: 14 - # Close an issue with no activity this long; a comment or a reopen restarts the - # clock. false turns it off. See /docs/maintainer-yml. - close_inactive_after_days: 30 - -# escalate: what stays with a human. -# - `always` is the schema default, written out so you can see it. -# - `ask_before_acting` is empty by default: no pull request waits on a human -# ack. Write categories (e.g. [large_pr, breaking_change]) to opt in. -# `pr.human_merge` paths still hold; security, license and CLA still escalate. -escalate: - always: [hostile_tone, direct_mention] - -# scout: the platform's daily survey of this repo files only what is already BROKEN -# (red CI, failing tests, a security advisory, a broken build or link) — never an -# improvement idea. `full` lets it file ideas too; `off` stops the survey. scout: survey: broken_only -# devops: match first-tier security advisories (KEV, NVD, GitHub, OSV) against what -# this repo runs, so a vulnerable dependency becomes work without anyone looking. devops: watch: advisories -# Proactive checkups, each a scout reading a brief you commit. Kept OFF on purpose: -# improvements here are wanted monthly at most, and a schedule is `days` + `hours_utc`, -# so once a week is the slowest it can fire. Enable these only when the platform -# grows a monthly cadence. -# schedules: -# # A weekly hygiene checkup: resource leaks, slow algorithms, duplicated helpers and -# # indexes, docs that drifted from the code, oversized or dead code. It reads the -# # brief at .dz/schedules/hygiene.md — edit that file to steer it, delete this entry to stop it. -# # It runs on your boxes and your key, and files what it finds as asks. -# - name: hygiene -# days: [sun] -# hours_utc: [23] -# brief_file: .dz/schedules/hygiene.md -# # A weekly devops checkup: a score on five axes (reliable, secure, fast, efficient, -# # cheap) and a list of findings, each with its evidence. It reads the brief at -# # .dz/schedules/devops.md — edit that file to steer it, delete this entry to stop it. -# # It runs on your boxes and your key, and files what it finds as asks. -# - name: devops -# days: [sat] -# hours_utc: [11] -# brief_file: .dz/schedules/devops.md +release: + # `none`: there is no release manager. Empty channels: the agent publishes nothing itself. + # The release is a `chore(release): ` PR (Cargo.toml, Cargo.lock, changelog); once it + # merges, an annotated `v` tag on the merge commit runs ci.yml, which pushes the image to + # GHCR and attaches the .deb files to the GitHub Release. See `.dz/briefs/release-due.md`. + manager: none + channels: [] + +escalate: + always: [hostile_tone, direct_mention] + # `breaking_change`: a human decides a change to the tool surface, CLI, config, auth flow or DB + # schema that a running install must react to. Security, license and CLA are the platform's + # hardcoded asks, which this list cannot remove. + ask_before_acting: [breaking_change] + +# The checkups nothing else triggers. One weekday per repo, so the fleet is not hit at once. +schedules: + # Weekly and judged, so a merge never cuts a release. + - name: release-due + days: [tue] + hours_utc: [3] + brief_file: .dz/briefs/release-due.md + # The one exception, so a confirmed security fix does not wait up to a week for the slot above. + - name: security-release + days: [mon, wed, thu, fri, sat, sun] + hours_utc: [6] + brief_file: .dz/briefs/security-release.md + # Weekly: the failures nothing announces. + - name: health + days: [tue] + hours_utc: [7] + brief_file: .dz/briefs/health.md + # Monthly: fires every Tuesday and the brief acts only on the first Tuesday of the month. + - name: improve + days: [tue] + hours_utc: [8] + brief_file: .dz/briefs/improve.md diff --git a/.dz/maintainer/reviewer.md b/.dz/maintainer/reviewer.md index fb9f449..205c258 100644 --- a/.dz/maintainer/reviewer.md +++ b/.dz/maintainer/reviewer.md @@ -7,16 +7,31 @@ ## Stack -Rust + Cargo (mise-managed toolchain). The gate is `bin/check` (`cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test`): a change that does not pass it is not proven, whatever its description says. +Rust 2024 + Cargo, toolchain pinned in `rust-toolchain.toml`. The gate is `bin/check` (`cargo fmt --check`, `cargo clippy --locked --all-targets -- -D warnings`, `cargo test --locked`, the e2e suite included): a change that does not pass it is not proven, whatever its description says. ## Review conventions -- TODO(setup): the conventions a reviewer must hold this repo to (from CLAUDE.md / CONTRIBUTING), each as a rule. +- The password and every token never appear in a response, an error, a log line or `Debug` output. Read the error and `Debug` paths, not just the happy path. Tokens are stored hashed. +- `/mcp` is bearer-only behind `auth::require_auth`, and every route but `/healthz` sits behind the `Host` allowlist guard. A change that weakens either is must-fix. +- Exactly three tools: `bash`, `job`, `file`. New capability is a param or an `action`, never a fourth tool. Args are `#[serde(deny_unknown_fields)]`. +- Output is bounded everywhere: poll pages newest-first under line/byte budgets, the live log is capped at 256 MiB, file reads page. An unbounded read or buffer is a finding. +- Kills: `kill(2)` only, the tri-state probe (unknown is never gone), success means the group probed gone, a pgid from another boot is never signalled. Callers only render a `KillOutcome`. +- The reaper never kills, and never ages out a running job. +- No `unwrap`/`expect` outside `main` and tests; no `std::sync::Mutex` on the request path; typed errors with `thiserror`. +- Files ≤300 non-test LOC; a new or removed `src` file updates CLAUDE.md's module map (`tests/module_map.rs` fails otherwise). +- A user-visible change adds its line to `docs/changelog/unreleased.md` in the same PR. +- `rust-toolchain.toml`, `Cargo.toml` `rust-version` and the Dockerfile base move together, in one PR. +- A security-path finding (auth, OAuth, config/credentials, command execution, signalling) is must-fix: there is no human merge behind the bot, so the review is the gate. ## Gates that matter -- TODO(setup): which checks decide a change here, and what "proven" means for a pull request. +- Required by the `main-protection` ruleset: `fmt` and `check`. `audit` (cargo audit) and `shellcheck` also run in `ci.yml`; a red one is a finding even though it does not block. +- The image job builds and smokes the container on every PR (`.github/scripts/smoke.sh`: healthz, OAuth, bash, job kill); the `deb` job installs the package in a clean Debian. Both prove the shipping artefacts, not just the code. +- `tests/public_tree.rs` scans every tracked file (minus `.dz/`) for facts about our own infrastructure. ## Never flag -- TODO(setup): what never to flag — generated or vendored files, style a formatter owns, conventions this repo chose on purpose. +- Style rustfmt and clippy own. +- The SHA-pinned GitHub Actions and the pinned toolchain: deliberate. Flag drift between the three toolchain pins, not the pinning. +- The `lukemathwalker/cargo-chef` Dependabot ignore: the toolchain moves by hand, in step. +- `docs/changelog/.md` pages: release notes, not code. diff --git a/.dz/schedules/devops.md b/.dz/schedules/devops.md index 06f9b5a..91caad6 100644 --- a/.dz/schedules/devops.md +++ b/.dz/schedules/devops.md @@ -1,10 +1,8 @@ - + # Devops checkup -This is the weekly devops checkup: a grade of how this repository ships, on five axes. You read files only: no shell, network or database. You also have the Signals block: recent CI job failures and failed tasks. +This is the devops grade the monthly `improve` checkup uses: a grade of how this repository ships, on five axes. You read files only: no shell, network or database. You also have the Signals block: recent CI job failures and failed tasks. **Evidence or nothing.** Every point lost names a `path:line` or a Signals line. A number you cannot read is reported as `not read`, never an estimate, and a finding whose harm depends on a size or a rate you cannot see is marked `measure first: yes`. Do not fix what is not broken. diff --git a/.dz/schedules/hygiene.md b/.dz/schedules/hygiene.md index f9c9dfe..017fd4c 100644 --- a/.dz/schedules/hygiene.md +++ b/.dz/schedules/hygiene.md @@ -1,10 +1,8 @@ - + # Hygiene checkup -This is the weekly hygiene checkup: a deep read for defects tests never show. You read files only: no shell, network or database, so a finding whose harm depends +This is the hygiene read the monthly `improve` checkup uses: a deep read for defects tests never show. You read files only: no shell, network or database, so a finding whose harm depends on a size or a rate you cannot see is marked `measure first: yes`, never guessed. ## What to look for diff --git a/.github/dependabot.yml b/.github/dependabot.yml index df8b034..c7fe2d7 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,4 +1,7 @@ -# Weekly, with minor and patch updates grouped per ecosystem; a major update arrives on its own. +# Cargo weekly; Docker and GitHub Actions monthly (as in developerz-ai/wurk: a weekly cadence there is +# mostly one PR per patch release for no change in what ships). Minor and patch updates are grouped +# per ecosystem; a major update arrives on its own. The developerz.ai maintainer agent reviews, +# fixes and merges every Dependabot PR (.dz/maintainer/maintainer.yml). # The 14-day cooldown lets a compromised release get caught before it reaches us. Security updates # are unaffected. version: 2 @@ -18,8 +21,7 @@ updates: - package-ecosystem: "docker" directory: "/" schedule: - interval: "weekly" - day: "monday" + interval: "monthly" time: "10:00" cooldown: default-days: 14 @@ -34,8 +36,7 @@ updates: - package-ecosystem: "github-actions" directory: "/" schedule: - interval: "weekly" - day: "monday" + interval: "monthly" time: "10:00" cooldown: default-days: 14 diff --git a/README.md b/README.md index 61ed546..daef2e2 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,18 @@

mcp-ssh

+
+ +[![Maintained by developerz.ai](https://img.shields.io/badge/maintained%20by-developerz.ai-8a2be2.svg)](#-ai-maintained) +[![CI](https://github.com/developerz-ai/mcp-ssh/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/developerz-ai/mcp-ssh/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/developerz-ai/mcp-ssh?sort=semver)](https://github.com/developerz-ai/mcp-ssh/releases/latest) +[![Image](https://img.shields.io/badge/image-ghcr.io-2496ED?logo=docker&logoColor=white)](https://github.com/developerz-ai/mcp-ssh/pkgs/container/mcp-ssh) +[![Rust](https://img.shields.io/badge/rust-1.100-CE422B?logo=rust&logoColor=white)](https://www.rust-lang.org) +[![GitHub stars](https://img.shields.io/github/stars/developerz-ai/mcp-ssh?style=flat&logo=github)](https://github.com/developerz-ai/mcp-ssh/stargazers) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + +
+ > **ssh, but you talk to it over `/mcp` from any MCP client.** > A single Rust binary that gives an AI agent a remote shell + file access to **one host — the box it runs on.** No SSH client, no multi-server fan-out, no gateway. It runs commands **locally**, as the service user, and speaks MCP over HTTP. @@ -143,6 +155,30 @@ Treat it accordingly: Rust 2024 · tokio · axum 0.8 · [rmcp](https://github.com/modelcontextprotocol/rust-sdk) 3.9 (MCP Streamable HTTP) · [rusqlite](https://github.com/rusqlite/rusqlite) (bundled SQLite — durable state, no system libsqlite). +## 🤖 AI-maintained + +mcp-ssh is maintained by AI: by [developerz.ai](https://developerz.ai), the way a human maintainer looks after an open-source project. The agent works publicly as `developerz-ai[bot]` and marks every comment it posts as bot-made. Its policy is committed in [`.dz/maintainer/maintainer.yml`](.dz/maintainer/maintainer.yml), and [`CLAUDE.md`](CLAUDE.md) binds it. + +| What arrives | What happens | +|---|---| +| an issue | triaged; asked for a reproduction when one is missing; a real bug is fixed and released | +| a pull request | reviewed (CodeRabbit and the developerz.ai reviewer, with a mandatory security pass), driven to green, merged | +| Dependabot | driven to green and merged; every bump waits 14 days after upstream publishes it (security updates excepted) | +| an outside change to CI, release or publish automation | declined: members maintain the pipeline that publishes the image and the `.deb` | +| a change that breaks a NEVER rule (secrets in output, root, no TLS, a fourth tool…) | declined with the rule quoted | +| a breaking change or a new feature | a human decides | + +Scheduled checkups, briefs in [`.dz/briefs/`](.dz/briefs/): weekly `release-due` judges whether a release is needed, daily `security-release` ships a confirmed security fix off-cycle, weekly `health` catches the failures nothing announces, and monthly `improve` lands at most three small, evidenced improvements, the Rust toolchain bump included. + +## ⭐ Star history + + + + + Star history of developerz-ai/mcp-ssh + + + ## 📄 License MIT. Repository: .