@kody/origin

import {
	DEFAULT_ORIGIN_ACCOUNT,
	DEFAULT_ORIGIN_SECRET_NAME,
	ORIGIN_APPS_DASHBOARD_URL,
	ORIGIN_PUBLIC_URL,
	ORIGIN_SECRET_SETUP_URL,
	accounts,
} from './token.ts'

/**
 * Describe the official Origin helpers package and required setup.
 *
 * This export does not call Origin or read secrets.
 *
 * @example
 * import describeOrigin from 'kody:@kody/origin'
 * const overview = await describeOrigin()
 */
export default async function describeOriginPackage() {
	return {
		package: '@kody/origin',
		kodyId: 'origin',
		publicUrl: ORIGIN_PUBLIC_URL,
		purpose:
			'Secret-safe Cursor Origin REST helpers for Kody agents: repos, pull requests, installations, and a raw request escape hatch.',
		auth: {
			lane: 'origin-app',
			secret: DEFAULT_ORIGIN_SECRET_NAME,
			storage: ['originAppId', 'originInstallationId'],
			algorithm: 'EdDSA',
			docs: 'coding_guide_get({ guide: "provider_origin" })',
			secretSetupUrl: ORIGIN_SECRET_SETUP_URL,
			appsDashboardUrl: ORIGIN_APPS_DASHBOARD_URL,
			note: 'Cloud Agents API keys (crsr_ / cursorApiKey) are not Origin credentials.',
		},
		defaultAccount: DEFAULT_ORIGIN_ACCOUNT,
		accounts: accounts(),
		jobsEnabled: false,
		mutationGuidance:
			'Non-GET originRequest calls and write helpers require dryRun: true to preview, then confirm: true to apply.',
		exports: {
			'.': 'Describe this package and required setup.',
			'./accounts': 'Origin App lane and multi-account selection guidance.',
			'./rate-limit': 'Zero-cost Origin rate-limit smoke test (app JWT).',
			'./auth': 'Sign an app JWT and mint an installation token (no token value).',
			'./installations': 'List app installations and installation-visible repos.',
			'./repos': 'List, get, or create Origin repositories (create is dryRun/confirm).',
			'./pulls':
				'List, get, create, update, or merge Origin pull requests (writes are dryRun/confirm).',
			'./request': 'Raw authenticated request to any /v1/origin path.',
			'./settings': 'Read or persist Origin App ids in package storage.',
			'./migrate-from-values':
				'Copy leftover originAppId / originInstallationId user values into package storage.',
			'./types': 'Shared TypeScript types.',
		},
	}
}