/**
 * Dropbox path constants and helpers for the Kody app folder.
 * Prefer listing root (`listFolder({ path: '' })`) before inventing paths.
 *
 * @example
 * import { APP_FOLDER_ROOT, underAppFolder } from 'kody:@kentcdodds/dropbox/paths'
 * const dest = underAppFolder('notes/hello.txt')
 * // => '/Apps/Kody/notes/hello.txt'
 */

/** Writable Kody app folder in full Dropbox path space. */
export const APP_FOLDER_ROOT = '/Apps/Kody'

/** Binary size above which `./upload` auto-delegates to `./upload-large` (120 KiB). */
export const UPLOAD_SINGLE_MAX_BYTES = 120 * 1024

/**
 * Preferred binary chunk size for upload sessions (~48 KiB).
 * Keeps each Dropbox append modest; put the full `bytesBase64` in execute `params`, never in `code`.
 */
export const UPLOAD_SESSION_CHUNK_BYTES = 48 * 1024

/**
 * Join a relative path under the Kody app folder.
 * Accepts `notes/a.txt`, `/notes/a.txt`, or an already-rooted `/Apps/Kody/...` path.
 */
export function underAppFolder(relativeOrAbsolute: string): string {
	const raw = typeof relativeOrAbsolute === 'string' ? relativeOrAbsolute.trim() : ''
	if (!raw) return APP_FOLDER_ROOT
	if (raw === APP_FOLDER_ROOT || raw.startsWith(`${APP_FOLDER_ROOT}/`)) return raw
	const trimmed = raw.replace(/^\/+/, '')
	if (trimmed.toLowerCase().startsWith('apps/kody/') || trimmed.toLowerCase() === 'apps/kody') {
		return `/${trimmed}`
	}
	return `${APP_FOLDER_ROOT}/${trimmed}`
}

/**
 * Suggest the app-folder prefix when a Dropbox path looks wrong (409 / not_found).
 */
export function suggestAppFolderPath(path: string): string {
	if (!path || path === '') return APP_FOLDER_ROOT
	if (path.startsWith(APP_FOLDER_ROOT)) return path
	if (path.startsWith('/Kody/') || path === '/Kody') {
		return underAppFolder(path.replace(/^\/Kody\/?/, ''))
	}
	return underAppFolder(path)
}

/**
 * Describe Dropbox path conventions for agents.
 *
 * @example
 * import paths from 'kody:@kentcdodds/dropbox/paths'
 * const overview = await paths()
 */
export default async function pathsOverview() {
	return {
		APP_FOLDER_ROOT,
		UPLOAD_SINGLE_MAX_BYTES,
		UPLOAD_SESSION_CHUNK_BYTES,
		primer:
			'List listFolder({ path: \'\' }) first. Writable Kody files live under /Apps/Kody/… — not /Kody/…. Use underAppFolder() for relative names.',
	}
}