|
| 1 | +--- |
| 2 | +title: Convex 1.36 release audits should ship one thin CLI slice |
| 3 | +date: 2026-04-26 |
| 4 | +category: workflow-issues |
| 5 | +module: kitcn cli |
| 6 | +problem_type: workflow_issue |
| 7 | +component: tooling |
| 8 | +severity: medium |
| 9 | +applies_when: |
| 10 | + - Auditing a newer Convex npm release for kitcn work |
| 11 | + - A Convex CLI feature can be exposed without wrapping its behavior |
| 12 | + - A Convex version bump changes scaffold pins or supported peer floors |
| 13 | +tags: [convex, cli, release-audit, env-default, fixtures, changeset] |
| 14 | +--- |
| 15 | + |
| 16 | +# Convex 1.36 release audits should ship one thin CLI slice |
| 17 | + |
| 18 | +## Context |
| 19 | + |
| 20 | +Convex 1.36 added several useful features: default environment variables, |
| 21 | +inline CLI queries, deployment messages, and function metadata reflection. |
| 22 | +That does not mean kitcn should mirror every feature. |
| 23 | + |
| 24 | +The useful slice was `convex env default`: kitcn already owns `kitcn env` |
| 25 | +delegation, and default env values improve new dev, preview, and production |
| 26 | +deployment setup without adding a new abstraction. |
| 27 | + |
| 28 | +## Guidance |
| 29 | + |
| 30 | +Treat Convex release audits as selection work, not a shopping spree: |
| 31 | + |
| 32 | +1. Read Ship, the package changelog, and the upstream diff. |
| 33 | +2. Classify each item as `compatibility`, `cleanup`, `agentic`, `feature`, or |
| 34 | + `no-op`. |
| 35 | +3. Ship one coherent slice. |
| 36 | +4. Prefer passthrough when Convex already owns the behavior. |
| 37 | + |
| 38 | +For Convex 1.36 default env values, the right shape is thin delegation: |
| 39 | + |
| 40 | +```bash |
| 41 | +kitcn env default list --type dev |
| 42 | +kitcn env default set SITE_URL https://app.example.com --type prod |
| 43 | +``` |
| 44 | + |
| 45 | +Do not add a kitcn-specific default-env store, parser, or lifecycle. Allow the |
| 46 | +subcommand, forward it to `convex env default`, and document the Convex-owned |
| 47 | +contract. |
| 48 | + |
| 49 | +When the selected slice depends on a new Convex CLI feature: |
| 50 | + |
| 51 | +- Pin scaffold/runtime installs to the exact supported version. |
| 52 | +- Raise package peer floors to the release family, for example `>=1.36`. |
| 53 | +- Update `www/` docs and packed Convex skill references in the same diff. |
| 54 | +- Write a changeset because published package behavior changed. |
| 55 | +- Run fixture sync/check when scaffold output package pins change. |
| 56 | + |
| 57 | +## Why This Matters |
| 58 | + |
| 59 | +kitcn gets worse when it shadows Convex. The package should sharpen agent and |
| 60 | +developer workflows, not become a second Convex CLI with stale copies of every |
| 61 | +new flag. |
| 62 | + |
| 63 | +Thin passthrough keeps ownership clean: Convex owns deployment defaults; kitcn |
| 64 | +owns discoverability, docs, scaffolds, and deterministic verification. |
| 65 | + |
| 66 | +## When to Apply |
| 67 | + |
| 68 | +- Convex ships a CLI subcommand that fits an existing kitcn command group. |
| 69 | +- A release includes several attractive features but only one has a small, |
| 70 | + proven kitcn integration path. |
| 71 | +- A Convex version bump affects scaffold pins, peer dependency warnings, or |
| 72 | + docs/skill setup guidance. |
| 73 | + |
| 74 | +## Examples |
| 75 | + |
| 76 | +Audit first: |
| 77 | + |
| 78 | +```bash |
| 79 | +npm view convex version --json |
| 80 | +gh api -H "Accept: application/vnd.github.raw" \ |
| 81 | + repos/get-convex/convex-backend/contents/npm-packages/convex/CHANGELOG.md |
| 82 | +git -C ../convex-backend diff <current-ref>..<target-ref> -- \ |
| 83 | + npm-packages/convex |
| 84 | +``` |
| 85 | + |
| 86 | +Then keep the implementation boring: |
| 87 | + |
| 88 | +```ts |
| 89 | +const SUPPORTED_ENV_SUBCOMMANDS = new Set([ |
| 90 | + "get", |
| 91 | + "set", |
| 92 | + "list", |
| 93 | + "default", |
| 94 | +]); |
| 95 | +``` |
| 96 | + |
| 97 | +For scaffold pin changes, verify both generated output and runtime: |
| 98 | + |
| 99 | +```bash |
| 100 | +bun run fixtures:sync |
| 101 | +bun run fixtures:check |
| 102 | +bun check |
| 103 | +``` |
| 104 | + |
| 105 | +## Related |
| 106 | + |
| 107 | +- [Convex 1.35 owns anonymous non-interactive setup](/Users/zbeyens/git/better-convex/docs/solutions/workflow-issues/convex-135-owns-anonymous-noninteractive-setup-20260415.md) |
0 commit comments