Skip to content
← Public packages

@kody/planetscale

Turn PlanetScale Insights anomalies into GitHub issues, implementer PRs, and a human review ping.

FollowFork

Files

README.md

105 lines · 4.7 KB · Markdown

@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.anomaly webhook 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 with autoCreatePR, 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.

  1. Create a token in the PlanetScale dashboard with at least read_organization, read_database, and Insights read. Add write_database only if you will create the branch.anomaly webhook from this package.
  2. 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
  1. Approve host api.planetscale.com.
  2. 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=user

Pass 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 createAgent with autoCreatePR)
  • Optional: fork @kody/notify if 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-loop defaults to { dryRun: true, wouldSave } and writes packageStorage() only with confirm: true
  • run-loop defaults to a preview; live GitHub issues, Cursor agents, and pings require confirm: true
  • create-webhook and mutating request calls throw unless confirm: true
  • The declared poll-anomalies job starts disabled. The insights webhook stays draft-only until configure-loop saves loopEnabled: true

Agents: see AGENTS.md for import paths, smoke checks, and loop snippets.

Done when

  • planetscaleApiToken is saved; host api.planetscale.com is 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-loop preview with dryRun: true before 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.

Docs