@charlesmatte/todos

import { getSettings } from './lib/store.ts'

/**
 * Overview of this shared multi-agent todo/task store: export list, call shapes, current time zone, rules,
 * and where the full docs live. Call first if unsure which export to use.
 *
 * @returns `{ package, docs, timeZone, exports, rules }`
 *
 * @example
 * import todos from 'kody:@charlesmatte/todos'
 *
 * const overview = await todos()
 */
export default async function describeTodos() {
	let settings: { timeZone: string; configured: boolean } | null = null
	try {
		settings = await getSettings()
	} catch {
		settings = null
	}
	return {
		package: 'todos — shared todo/task/reminder store for AI agents',
		docs: 'Full reference: package README.md (search entity "package:<owner>/todos#README.md"); agent notes: AGENTS.md.',
		timeZone: settings?.timeZone ?? 'UTC',
		timeZoneConfigured: settings?.configured ?? false,
		exports: {
			'./create': '{ title, by, notes?, due?, priority?, tags?, kind?, project?, client?, timeZone? } → { todo, line }',
			'./list': '{ status?, overdue?, today?, dueBefore?, dueAfter?, undated?, tag?, project?, client?, kind?, priority?, q?, includeDeleted?, limit?, timeZone? } → { todos, text }',
			'./get': '{ id, timeZone? } → { todo (with history) }',
			'./update': '{ id, by, title?, notes?, due?, clearDue?, snooze?: {days|hours|until}, priority?, kind?, tags?, addTags?, removeTags?, project?, client?, timeZone? }',
			'./complete': '{ id, by, note? }',
			'./reopen': '{ id, by } (also restores deleted)',
			'./delete': '{ id, by, purge? } (soft delete by default)',
			'./digest': '{ days?, includeUndated?, tag?, project?, client?, timeZone? } → { counts, text }',
			'./settings': '{ timeZone? } → { timeZone, configured } (set once after install; default UTC)',
		},
		rules: [
			'Always pass `by` (your agent name) on writes; it is recorded in history.',
			'Due dates without an offset use the store time zone (./settings) or a per-call `timeZone`. "YYYY-MM-DD" = all-day.',
			'Unknown input keys are rejected with the accepted shape.',
			'Ids look like "T12"; "12" is accepted too.',
		],
	}
}