feat(coffee): Add auto-caffeinate when Raycast launches

[Official-Krish]

Fixes #29965

Description

Adds an "instant on" feature to the Coffee extension, addressing the request to automatically keep the Mac awake whenever Raycast launches (like Amphetamine's "start when app opens").
A new "Start caffeination when Raycast starts" preference (checkbox, default off) makes Coffee caffeinate the Mac indefinitely shortly after Raycast starts — no manual action needed.

How it works

• Raycast has no true "on launch" hook, so the feature piggybacks on the extension's existing background refresh: the Caffeinate Status command (15s) and the menu bar command (1m).
• A new maybeAutoCaffeinate() helper (in src/status.ts) records the last background run in LocalStorage. When the gap since the last run exceeds 2 minutes, it means Raycast was quit (or the Mac was asleep) — i.e., a fresh session — so it starts caffeinate indefinitely via startCaffeinate().
• Because the marker is refreshed on every background tick (before the early returns), manually decaffeinating stays in effect for the rest of the session; the Mac re-caffeinates only on the next Raycast restart.
• The helper is wired into both the status command and the menu bar command so it works regardless of which background refresh is active.

Supporting fix

• The new LocalStorage key exposed a latent bug: useLoadStoredSchedules did a blind JSON.parse on every stored value and would have crashed the Schedule Caffeination view on the numeric marker. Extracted a shared parseSchedule validator (already used by the AI schedule-listing tool) and applied it in the schedule loader.

Changes

• package.json — new startCaffeinateOnLaunch preference
• src/status.ts — maybeAutoCaffeinate() + wiring into the status command
• src/index.tsx — call the helper once the menu bar status loads
• src/utils.ts — extracted parseSchedule
• src/hooks/useLoadStoredSchedules.tsx, src/tools/list-caffeination-schedules.ts — use the shared validator
• README.md, CHANGELOG.md — documented the feature

Checklist

• I read the extension guidelines
• I read the documentation about publishing
• I ran npm run build and tested this distribution build in Raycast
• I checked that files in the assets folder are used by the extension itself
• I checked that assets used in the README are located outside the metadata folder if they were not generated with our metadata tool

[raycastbot]

Thank you for your contribution! 🎉

🔔 @mooxl @bibixx @GastroGeek @pernielsentikaer @xilopaint @ridemountainpig @zakj @Visual-Studio-Coder @IKatsuba @alexibuild @mbuvarp @frederikobermaier-lab @bsradcliffe you might want to have a look.

You can use this guide to learn how to check out the Pull Request locally in order to test it.

📋 Quick checkout commands

BRANCH="feat(coffee)/auto-caffeinate-on-launch"
FORK_URL="https://github.com/Official-Krish/extensions.git"
EXTENSION_NAME="coffee"
REPO_NAME="extensions"

git clone -n --depth=1 --filter=tree:0 -b $BRANCH $FORK_URL
cd $REPO_NAME
git sparse-checkout set --no-cone "extensions/$EXTENSION_NAME"
git checkout
cd "extensions/$EXTENSION_NAME"
npm install && npm run dev

We're currently experiencing a high volume of incoming requests. As a result, the initial review may take up to 15 business days.

[greptile-apps]

Greptile Summary

The PR adds opt-in automatic caffeination when a new Raycast session is detected and makes schedule loading ignore unrelated LocalStorage entries.

• Adds a launch preference and documents its background-command requirements.
• Tracks Raycast sessions and invokes indefinite caffeination once per session.
• Shares schedule parsing and validation between the schedule UI and AI listing tool.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
extensions/coffee/src/status.ts	Adds Raycast-session detection and coordinates once-per-session automatic caffeination with existing schedule handling.
extensions/coffee/src/index.tsx	Invokes automatic caffeination after the menu-bar command finishes loading its process status.
extensions/coffee/src/utils.ts	Extracts the shared validator used to distinguish schedules from unrelated LocalStorage values.
extensions/coffee/src/hooks/useLoadStoredSchedules.tsx	Filters stored values through the shared schedule validator before sorting and displaying them.
extensions/coffee/src/tools/list-caffeination-schedules.ts	Reuses the shared schedule parser instead of maintaining a duplicate implementation.
extensions/coffee/package.json	Adds the opt-in checkbox preference for automatic launch-time caffeination.
extensions/coffee/README.md	Documents the feature, required background commands, and session-detection behavior.
extensions/coffee/CHANGELOG.md	Records the new feature using the repository merge-date placeholder convention.

_{Reviews (3): Last reviewed commit: "fix(coffee): auto-caffeinate on Raycast ..." | Re-trigger Greptile}

[pernielsentikaer]

Hi @Official-Krish 👋

Thanks for your contribution 💪

I have now tested your extension, and I have some feedback ready for you:

• Sleep/wake ≠ Raycast relaunch — now - lastRun >= 2 minutes also becomes true after the Mac has been asleep (background intervals do not tick during sleep). After a user Decaffeinates, closes the lid for a while, then wakes, the next status / menu-bar tick can silently start indefinite caffeinate again. That breaks the promise that manual decaf lasts until the next Raycast restart. Please key “new session” off something stable across sleep/wake but new when Raycast actually relaunches (e.g. Raycast app PID / process start time in LocalStorage), and re-test: quit/relaunch with the pref on, manual decaf → sleep/wake without quitting Raycast, schedule interaction, and pref-off as a no-op.
• Give the preference its own title (e.g. "Launch") so it does not sit under Menu Bar Icon, and mention in the description/README that Caffeinate Status and/or the menu bar command must stay enabled for the feature to run.
• Match existing Coffee checkbox labels with sentence case (Start caffeination when Raycast starts). A short HUD on the auto-start path would also make the behavior easier to notice while testing.

I'm looking forward to testing this extension again 🔥

Feel free to contact me here or at Slack if you have any questions.

---

Please convert this PR to a draft while working on the requested changes. Once ready, mark it as ready for review again and we'll take another look. Thanks!

[Official-Krish]

@pernielsentikaer I’ve addressed all the points you mentioned. If you find anything else let me know.

[Visual-Studio-Coder]

@Official-Krish add me to "past-contributors" in the manifest please @copilot do it my username is Visual-Studio-Coder just put it in the package json (check raycast docs to know where to add it or smth idk)