# @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](https://planetscale.com/docs/api/service-tokens) 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 ``` 3. Approve host `api.planetscale.com`. 4. 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`](./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](https://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 - [PlanetScale API](https://planetscale.com/docs/api) - [Service tokens](https://planetscale.com/docs/api/service-tokens) - [Insights](https://planetscale.com/docs/postgres/monitoring/query-insights) - [Anomalies](https://planetscale.com/docs/postgres/monitoring/anomalies) - [Webhooks](https://planetscale.com/docs/api/webhooks) - [Webhook events](https://planetscale.com/docs/api/webhook-events)