@kody/planetscale
Turn PlanetScale Insights anomalies into GitHub issues, implementer PRs, and a human review ping.
Files
@kody/planetscale — agent notes
Human setup and intent live in README.md. This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
name only — never paste key values. Do not disable live webhooks or jobs.
Auth
| Item | Value |
|---|---|
| Secret | planetscaleApiToken (id:token, no scheme) |
| Optional HMAC | planetscaleWebhookSecret (X-PlanetScale-Signature, SHA-256 hex) |
| Host | api.planetscale.com |
| Multi-account | account: "work" → planetscaleApiToken-work; or secretName |
Placeholder: {{secret:planetscaleApiToken|scope=user}}.
Live loop steps also need GitHub OAuth, a Cursor API key, and (optional) a
forked @kody/notify. Prefer kody:@kody/github/request,
kody:@kody/cursor/agents, and kody.emailSend.
Import paths
| Export | Import |
|---|---|
| action dispatcher (defaults to overview) | kody:@kody/planetscale |
| accounts | kody:@kody/planetscale/accounts |
| smoke-test | kody:@kody/planetscale/smoke-test |
| list-organizations | kody:@kody/planetscale/list-organizations |
| list-databases | kody:@kody/planetscale/list-databases |
| list-branches | kody:@kody/planetscale/list-branches |
| list-anomalies | kody:@kody/planetscale/list-anomalies |
| list-queries | kody:@kody/planetscale/list-queries |
| draft-loop | kody:@kody/planetscale/draft-loop |
| configure-loop | kody:@kody/planetscale/configure-loop |
| run-loop | kody:@kody/planetscale/run-loop |
| handle-webhook | kody:@kody/planetscale/handle-webhook |
| poll-anomalies | kody:@kody/planetscale/poll-anomalies |
| create-webhook | kody:@kody/planetscale/create-webhook |
| request (escape hatch) | kody:@kody/planetscale/request |
| types | kody:@kody/planetscale/types |
Prefer static kody:@kody/planetscale/... imports from execute. Do not lead
with packages.invoke.
Smoke test (read-only)
import smokeTest from 'kody:@kody/planetscale/smoke-test'
export default async function main() {
return await smokeTest()
// without creds => { ok: true, live: false, setup: { ...URLs }, fixture draft }
// with creds => lists orgs; never opens issues or agents; no billing emails
}Loop snippets
Preview then (only after human approval) run:
import runLoop from 'kody:@kody/planetscale/run-loop'
export default async function main() {
const preview = await runLoop({
organization: 'acme',
database: 'app',
branch: 'main',
githubOwner: 'acme',
githubRepo: 'app',
dryRun: true,
})
// live: await runLoop({ ...same targets, confirm: true })
return preview
}Configure targets after fork (dryRun / confirm):
import configureLoop from 'kody:@kody/planetscale/configure-loop'
import runLoop from 'kody:@kody/planetscale/run-loop'
export default async function main() {
await configureLoop({
organization: 'acme',
database: 'app',
branch: 'main',
githubOwner: 'acme',
githubRepo: 'app',
repositoryUrl: 'https://github.com/acme/app',
confirm: true,
})
return await runLoop({ dryRun: true })
}Enable webhook/poll-driven issue creation only when the caller asks:
import configureLoop from 'kody:@kody/planetscale/configure-loop'
export default async function main() {
return await configureLoop({ loopEnabled: true, confirm: true })
}Preview PlanetScale webhook creation:
import createWebhook from 'kody:@kody/planetscale/create-webhook'
export default async function main() {
return await createWebhook({
organization: 'acme',
database: 'app',
url: 'https://YOUR-KODY-INSIGHTS-WEBHOOK',
dryRun: true,
})
}dryRun / confirm (writes)
| Export | Behavior |
|---|---|
configure-loop | Defaults dry-run; writes storage only with confirm: true |
run-loop | Preview by default; live issue/agent/ping needs confirm: true |
create-webhook / mutating request | Throws unless confirm: true; dryRun: true previews |
createAgent has no dry-run — never call run-loop live without
confirm: true. Do not flip poll-anomalies enabled or rewire the
insights webhook unless the user explicitly asks.
Edge cases
- REST base:
https://api.planetscale.com/v1 - List helpers return
{ items, pageInfo } - Insights dashboard URLs:
https://app.planetscale.com/{org}/{db}/{branch}/insights branch.anomalybodies includeorganization,database, andresource.name(branch); the handler then lists Insights anomalies- Dedup: last processed anomaly id lives in
packageStorage() - Job
poll-anomaliesshipsenabled: false; leave it alone unless asked