@kody/raycast

import { kody } from 'kody:runtime'
import {
	KODY_ID,
	OFFICIAL_PACKAGE_ID,
	PACKAGE_NAME,
	PUBLIC_URL,
	asRecord,
	invocationUrl,
	optionalString,
	tokenSetupUrl,
} from './helpers.ts'

export type GuideInput = {
	packageId?: string
	username?: string
}

/**
 * Agent setup: preferred webhook config path plus optional invocation-token URL.
 *
 * Preferred auth for Raycast is minted `list-commands` / `run` webhooks stored in
 * `~/.config/kody/raycast.json` (never in chat). Package invocation tokens remain
 * available for list-packages / get-package / invoke HTTP clients.
 *
 * @example
 * import guide from 'kody:@kody/raycast/guide'
 * const setup = await guide()
 */
export default async function guide(input: GuideInput = {}) {
	const record = asRecord(input)
	const username = optionalString(record, 'username') ?? 'YOUR_USERNAME'
	let packageId = optionalString(record, 'packageId')

	if (!packageId) {
		const listed = await kody.packageList({})
		packageId =
			listed.packages.find(pkg => pkg.kody_id === KODY_ID)?.package_id ??
			OFFICIAL_PACKAGE_ID
	}

	const setupUrl = tokenSetupUrl(packageId)
	return {
		name: PACKAGE_NAME,
		kodyId: KODY_ID,
		publicUrl: PUBLIC_URL,
		packageId,
		preferredAuth: 'minted-webhooks',
		configPath: '~/.config/kody/raycast.json',
		auth: 'minted-webhooks-or-package-invocation-token',
		secrets: [],
		secretUrls: {},
		tokenSetupUrl: setupUrl,
		invocation: {
			method: 'POST',
			listPackagesUrl: invocationUrl(username, 'list-packages'),
			getPackageUrl: invocationUrl(username, 'get-package'),
			invokeUrl: invocationUrl(username, 'invoke'),
			guideUrl: invocationUrl(username, 'guide'),
			source: 'raycast',
		},
		steps: [
			'Share https://kody.codes/@kody/raycast — not a /community/{listing_id} URL.',
			'For a personal launcher, fork or install this listing, then call ./adapt.',
			'Mint list-commands + run webhooks and write them to ~/.config/kody/raycast.json (preferred for Raycast).',
			`Optional legacy token form: ${setupUrl}`,
			`Optional POST https://kody.codes/@${username}/api/package-invocations/raycast/<export> with Authorization: Bearer <token>.`,
			'Call ./upsert-command to add stored execute scripts; open Kody Commands in Raycast.',
			'Mutations on ./invoke support dryRun: true (preview, no target call).',
			'Never paste webhook URLs, invocation tokens, or other secrets into chat.',
		],
	}
}