# @kody/planetscale — agent notes Human setup and intent live in [`README.md`](./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) ```js 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: ```js 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`): ```js 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: ```js import configureLoop from 'kody:@kody/planetscale/configure-loop' export default async function main() { return await configureLoop({ loopEnabled: true, confirm: true }) } ``` Preview PlanetScale webhook creation: ```js 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.anomaly` bodies include `organization`, `database`, and `resource.name` (branch); the handler then lists Insights anomalies - Dedup: last processed anomaly id lives in `packageStorage()` - Job `poll-anomalies` ships `enabled: false`; leave it alone unless asked