Skip to content
← Public packages

@kody/planetscale

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

FollowFork

Files

AGENTS.md

145 lines · 4.5 KB · Markdown

@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

ItemValue
SecretplanetscaleApiToken (id:token, no scheme)
Optional HMACplanetscaleWebhookSecret (X-PlanetScale-Signature, SHA-256 hex)
Hostapi.planetscale.com
Multi-accountaccount: "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

ExportImport
action dispatcher (defaults to overview)kody:@kody/planetscale
accountskody:@kody/planetscale/accounts
smoke-testkody:@kody/planetscale/smoke-test
list-organizationskody:@kody/planetscale/list-organizations
list-databaseskody:@kody/planetscale/list-databases
list-brancheskody:@kody/planetscale/list-branches
list-anomalieskody:@kody/planetscale/list-anomalies
list-querieskody:@kody/planetscale/list-queries
draft-loopkody:@kody/planetscale/draft-loop
configure-loopkody:@kody/planetscale/configure-loop
run-loopkody:@kody/planetscale/run-loop
handle-webhookkody:@kody/planetscale/handle-webhook
poll-anomalieskody:@kody/planetscale/poll-anomalies
create-webhookkody:@kody/planetscale/create-webhook
request (escape hatch)kody:@kody/planetscale/request
typeskody:@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)

ExportBehavior
configure-loopDefaults dry-run; writes storage only with confirm: true
run-loopPreview by default; live issue/agent/ping needs confirm: true
create-webhook / mutating requestThrows 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