@kody/planetscale
Turn PlanetScale Insights anomalies into GitHub issues, implementer PRs, and a human review ping.
Files
@kody/planetscale
Intent
Reusable PlanetScale Insights helpers so a forked Kody package can turn a slow query into the loop people actually want: open a GitHub issue, launch an implementer that opens a PR, let a reviewer agent look at that PR, then ping a human. Success is a dry-run draft you can inspect, then a confirmed run that does not start from scratch each time.
This listing is meant to be forked. After you fork, save your own
planetscaleApiToken, point configure-loop at your org/database/repo, and
keep loopEnabled off until you want webhooks or the poll job to create
issues. No personal organization ids, database names, or tokens are hard-coded.
Share this package as https://kody.codes/@kody/planetscale
(never a /community/{listing_id} URL).
What it does
- Detect Insights anomalies (
branch.anomalywebhook or a poll job) - Draft a GitHub issue body, implementer prompt, reviewer prompt, and human ping
- After
confirm: true, open the issue, launch a Cursor Cloud implementer withautoCreatePR, request a reviewer, and email-ping the signed-in Kody user - Remember the last processed anomaly id in
packageStorage()so the same signal does not open a new issue every poll - Read-only list helpers for organizations, databases, branches, anomalies, and Insights queries
Prerequisites / setup
PlanetScale service tokens are sent as
Authorization: SERVICE_TOKEN_ID:SERVICE_TOKEN with no scheme. Save that
exact id:token value in Kody. Do not paste tokens into chat.
- Create a token in the PlanetScale dashboard
with at least
read_organization,read_database, and Insights read. Addwrite_databaseonly if you will create thebranch.anomalywebhook from this package. - Save it in Kody:
https://kody.codes/account/secrets/new?name=planetscaleApiToken&description=PlanetScale%20service%20token%20as%20SERVICE_TOKEN_ID%3ASERVICE_TOKEN%20for%20api.planetscale.com&allowedHosts=api.planetscale.com&scope=user- Approve host
api.planetscale.com. - Optional webhook HMAC secret (header
X-PlanetScale-Signature, SHA-256 hex):
https://kody.codes/account/secrets/new?name=planetscaleWebhookSecret&description=PlanetScale%20webhook%20HMAC%20secret%20(X-PlanetScale-Signature)&allowedHosts=api.planetscale.com&scope=userPass account: "work" to use secret planetscaleApiToken-work, or pass
secretName: "planetscaleApiToken-work". There are no hard-coded account aliases.
Hosts and dependent services
api.planetscale.com— all REST calls (required)- GitHub OAuth:
https://kody.codes/connect/oauth?provider=github - Cursor API key (for live
createAgentwithautoCreatePR) - Optional: fork
@kody/notifyif you want Slack/Discord/Telegram fanout
createAgent has no dry-run. This package never calls it unless confirm: true.
The implementer prompt tells the Cursor agent to open the PR itself with
ManagePullRequest. Kody does not open that PR as a substitute.
Mutation safety (summary)
configure-loopdefaults to{ dryRun: true, wouldSave }and writespackageStorage()only withconfirm: truerun-loopdefaults to a preview; live GitHub issues, Cursor agents, and pings requireconfirm: truecreate-webhookand mutatingrequestcalls throw unlessconfirm: true- The declared
poll-anomaliesjob starts disabled. Theinsightswebhook stays draft-only untilconfigure-loopsavesloopEnabled: true
Agents: see AGENTS.md for import paths, smoke checks, and
loop snippets.
Done when
planetscaleApiTokenis saved; hostapi.planetscale.comis approved- Smoke test returns
{ ok: true, live: true, … }(or{ live: false }plus setup URLs when credentials are missing) without opening issues or agents configure-loop/run-looppreview withdryRun: truebefore any live run- Webhooks and the poll job stay disabled until you explicitly set
loopEnabled: true
Branding
community-icon.svg is PlanetScale's official white logomark from
planetscale.com/brand
(planetscale-logo-mark-white.svg on black #000000). Paths are unmodified
except for a square tile so the mark stays legible at 56 pixels.
PlanetScale® is a trademark of PlanetScale, Inc. This package is not
affiliated with or endorsed by PlanetScale.