packaging(snap): the Snap Store release is manual and ungated — nothing catches drift between snapcraft.io and the tree

[MSKazemi]

Summary

The snap at https://snapcraft.io/kubeintellect is in sync today — but only by
coincidence. Nothing in the repo or in CI compares what the store serves against what the
tree says, and publishing is a manual workflow_dispatch. A kube-q version bump can merge
to main with every required check green while the store keeps serving the previous
version indefinitely, and no gate goes red.

That is the same failure shape as #66
(PyPI behind the source tree) and #56
(a Homebrew formula pinned to a version that never existed): a distribution surface whose
claim about itself is ungated.

What the store actually serves right now

Measured 2026-09-11 via api.snapcraft.io (not the web page, not the publisher console):

$ curl -sH 'Snap-Device-Series: 16' \
    'https://api.snapcraft.io/v2/snaps/info/kubeintellect?fields=version,revision,confinement'

arch	channel	version	revision	confinement
amd64	stable	1.6.0	6	strict
arm64	stable	1.6.0	5	strict
arm64	edge	1.6.0	5	strict
amd64	edge	(none — falls back to stable)	—	—

Listing metadata: title KubeIntellect (kq), website https://kubeintellect.com, license
AGPL-3.0-or-later, categories development + server-and-cloud, publisher
mohsenseyedkazemi (validation: unproven), media = 1 icon + 1 banner + 4 screenshots +
1 video (youtube.com/watch?v=PdVPw1s9lqA).

And in the tree: v4/packages/kube-q/pyproject.toml is version = "1.6.0", which is what
snap/snapcraft.yaml's override-pull feeds to craftctl set version. So store == tree,
today. Nothing proves that tomorrow.

The gaps

1. Publishing never happens on its own. In .github/workflows/snap.yml the publish
job is gated on github.event_name == 'workflow_dispatch' && inputs.channel != ''. A push to
main that touches v4/packages/kube-q/** runs build — which is a genuine gate, it
installs the snap and smoke-tests --version/--help/completion — and then stops. Releasing
is a human remembering to open the Actions tab and pick a channel.

2. Nothing detects the drift that causes. v4/scripts/check_doc_claims.py has no snap
awareness (grep -n snap on it returns nothing), and no other gate touches the store. The
README.md Snap Store badge is a live shields.io query of the store, so when the store goes
stale the badge silently advertises the stale version next to a PyPI badge advertising the
current one — the badge reports the drift instead of failing on it.

3. The two version numbers in the badge row mean different things and nothing says so.
README.md:7 shows PyPI kubeintellect (2.4.1, the server) and README.md:9 shows the
snap (1.6.0, the kq client, because the snap version tracks
v4/packages/kube-q/pyproject.toml). Both badges sit in the same row under one project
name. A visitor has no way to tell that these are not the same thing versioned
inconsistently.

4. The root README advertises the snap but never tells you how to install it. The badge
is on line 9; the "Install the CLI" block on line 56 offers only pip install kube-q. The
snap install lines exist in v4/packages/kube-q/{README.md,docs/installation.md, docs/quickstart.md,docs/index.md} — and nowhere in v4/docs/, the site published at
kubeintellect.com (grep -rn "snap install\|snapcraft" v4/docs/ → 0 hits).

5. Channel state is ragged. amd64 has no edge (it falls back to stable — harmless but
inconsistent with arm64, which has one), no arch has beta or candidate, and the two
stable revisions differ (6 vs 5) for the same version. Worth deciding deliberately rather
than inheriting whatever the last manual dispatch left behind.

Proposed work

• Add a scripts/check-snap-release.py (repo-root, no virtualenv, same shape as
  check-file-modes.sh / check-syntax-warnings.py) that reads the version from
  v4/packages/kube-q/pyproject.toml, queries
  api.snapcraft.io/v2/snaps/info/kubeintellect, and fails when stable on either
  arch is behind it. It must fail — not pass — when it can reach no channels at all, for
  the same reason the mode and syntax gates fail on an empty scan.
• Wire it into make check-snap, and — if it becomes CI — add it to an existing job
  rather than a new one. A new job name is a check main does not require, and per
  .github/required-checks.yml that has to be a decision,
  not a side effect. Network-dependent, so a soft-fail/scheduled run may be the better
  home than a PR gate.
• Decide whether snap.yml should auto-release to edge on every push to main that
  changes v4/packages/kube-q/**, keeping stable manual. That closes the drift window
  without making an unreviewed commit publish to users.
• Add the snap install kubeintellect path (plus the two mandatory snap connect lines
  and the optional snap alias) to the root README.md install block and to v4/docs/,
  so every surface carrying the badge also carries the instructions.
• Label the two badges so 2.4.1 (server) and 1.6.0 (kq client) do not read as one
  project contradicting itself.
• Decide the channel policy — whether edge/beta/candidate should exist on both
  arches or on neither — and record it next to snap/snapcraft.yaml.

Notes for whoever picks this up

• Verify against api.snapcraft.io, never the publisher console's success banner. The
  console has reported a successful save for a listing change that did not land.
• snap/snapcraft.yaml is the source of truth for the listing's text fields (title,
  summary, description, links, website) — those are re-synced to the store on a stable
  release, so an edit made only in the web console is overwritten by the next publish.
  Media (icon, banner, screenshots, video) is console-only and is not touched by a release.
  Re-confirm this on the next publish rather than taking it on trust.
• Store screenshots must be 1–30 fps and ≤40 s; the cast-rendered GIFs are ~0.5 fps and
  are rejected as-is.
• The publisher is currently unproven. Separate question from this issue, but it is
  what a visitor sees on the page.