raycast-extension

name	raycast-extension
description	Build and maintain the What Time Is It There Raycast extension with strict type safety, Bun tooling, OXC lint/format, and reliable timezone conversion behavior.

Raycast Extension Skill: What Time Is It There

Use this skill when working on /Users/staggart/dev/raycast-what-time-is-it-there.

Goal

Preserve a minimal, reliable scheduling workflow where users can quickly convert a proposed time in one timezone into their primary and saved timezones.

Architecture

• Command UI:
  • src/convert-time.tsx
  • src/manage-timezones.tsx
• Shared form:
  • src/components/TimezoneSettingsForm.tsx
• Business logic:
  • src/lib/time-input.ts
  • src/lib/conversion.ts
  • src/lib/settings.ts
  • src/lib/timezone-data.ts
• Tests:
  • src/lib/time-input.test.ts
  • src/lib/conversion.test.ts

Product Rules

• First-run experience must request:
  • primary timezone
  • at least one saved timezone
• Settings must persist across launches using Raycast LocalStorage.
• Main flow should stay fast:
  • enter time in list search bar
  • optional source timezone dropdown
  • immediate converted list
• Primary timezone should always appear first in results.

Implementation Rules

• Keep edits small and focused; no unnecessary abstractions.
• No any; no non-null assertions.
• Prefer compile-time safety over runtime patching.
• Keep parsing/conversion logic inside src/lib/ and test there.
• UI components should orchestrate state, not implement conversion math.

Raycast API Guidance

• Use List for rapid entry + result display.
• Use Form for setup and settings management.
• Use ActionPanel for copy actions and settings navigation.
• Use showToast for save/load feedback.
• Use LocalStorage for persistence.

Time Parsing and Conversion Expectations

• Parse supported input formats:
  • 2pm, 10:30am, 14:00, 930
  • optional trailing timezone token (e.g. EST, CT, America/New_York)
• If timezone token is missing, use selected source timezone.
• Display each row with:
  • local time
  • date
  • day-shift label
  • UTC offset

Quality Gates (Always Run)

bun run typecheck
bun run lint
bun run format
bun test

If formatting fails:

bun run format:write

Tooling Constraints

• Package manager: Bun
• Linting: OXC (oxlint)
• Formatting: OXC formatter (oxfmt)
• Tests: Bun test runner
• Pre-commit: Husky hook at .husky/pre-commit

Safe Change Checklist

1. Update or add tests for logic changes.
2. Verify primary timezone ordering in conversion results.
3. Verify saved timezone persistence and onboarding behavior.
4. Run all quality gates.
5. Keep command UX simple and predictable.

Canonical References

• Raycast List: https://developers.raycast.com/api-reference/user-interface/list
• Raycast Form: https://developers.raycast.com/api-reference/user-interface/form
• Raycast LocalStorage: https://developers.raycast.com/api-reference/storage
• Raycast extension lifecycle: https://developers.raycast.com/information/lifecycle
• OXC linter usage: https://oxc.rs/docs/guide/usage/linter
• OXC formatter usage: https://oxc.rs/docs/guide/usage/formatter