Add a cooldown condition

[frenck]

Description

Adds a second Spook condition: spook.cooldown.

It passes only if this automation or script has not run within a configured duration (or has never run). It is a built-in cooldown, so an automation does not re-fire too often. This replaces the copy-pasted {{ now() - this.attributes.last_triggered > timedelta(...) }} template that shows up everywhere.

It reads the this variable (the running automation or script's own state), which Home Assistant captures before the current run updates last_triggered, so the comparison is against the previous run and the cooldown actually holds. last_triggered is handled whether it arrives as a datetime or as a restored ISO string, and the condition passes gracefully when there is no run context.

This is the first condition added as a pure leaf module on top of the condition platform from #1386: a single file under ectoplasms/spook/conditions/ plus its conditions.yaml and translation entry. condition.py was not touched.

Motivation and Context

A per-automation cooldown is one of the most copy-pasted template conditions in Home Assistant. Making it a first-class condition removes that boilerplate.

How has this been tested?

• The condition is discovered as spook.cooldown.
• Config validation accepts a duration and rejects a missing one.
• A run within the cooldown fails; a run older than the cooldown passes; a restored ISO-string last-triggered is parsed; and it passes when there is no last-run information.
• Full suite green (716 passed), ruff + pylint (10.00/10) + prettier clean.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Other

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 609fab7e-d4df-4966-9ea9-f1e7e93da6db

📥 Commits

Reviewing files that changed from the base of the PR and between eca315c and 63869ff.

📒 Files selected for processing (4)

• custom_components/spook/conditions.yaml
• custom_components/spook/ectoplasms/spook/conditions/cooldown.py
• custom_components/spook/translations/en.json
• tests/ectoplasms/spook/conditions/test_cooldown.py

---

📝 Walkthrough

Walkthrough

This PR adds a new "cooldown" condition to the Spook integration. It defines a YAML config schema and duration selector, implements SpookCondition to check elapsed time since last trigger, adds translation strings, and includes tests covering registration, validation, and evaluation behavior.

Changes

Cooldown Condition

Layer / File(s)	Summary
Config schema and translations custom_components/spook/conditions.yaml, custom_components/spook/translations/en.json	Adds a cooldown block requiring a duration field with a duration selector, plus matching localized name/description strings.
SpookCondition implementation custom_components/spook/ectoplasms/spook/conditions/cooldown.py	Implements SpookCondition (condition type "cooldown") with a voluptuous schema for duration, a _last_triggered helper parsing datetime/string values, and _async_check logic passing when no prior trigger exists or the cooldown period has elapsed.
Tests tests/ectoplasms/spook/conditions/test_cooldown.py	Adds tests validating condition registration, config validation (valid/invalid duration), and evaluation across recent, elapsed, ISO-string, and missing last_triggered scenarios.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
    participant Automation
    participant SpookCondition
    participant LastTriggeredHelper

    Automation->>SpookCondition: async_validate_config(config)
    SpookCondition-->>Automation: validated config with duration

    Automation->>SpookCondition: _async_check(variables)
    SpookCondition->>LastTriggeredHelper: _last_triggered(variables)
    LastTriggeredHelper-->>SpookCondition: datetime or None
    alt no last_triggered
        SpookCondition-->>Automation: True (pass)
    else last_triggered present
        SpookCondition->>SpookCondition: compare utcnow() - last_triggered vs duration
        SpookCondition-->>Automation: True/False
    end

Loading

Poem

A rabbit checks the clock with care,
"Not yet, not yet!" it thumps the air. 🐇⏱️
Five minutes pass, cooldown complete,
Hop through the gate on quiet feet.
Test after test, all snug and tight—
Cooldown condition, out of the burrow tonight! 🌙

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a new cooldown condition.
Description check	✅ Passed	The description is directly related to the changeset and accurately explains the new cooldown condition.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch frenck/condition-cooldown

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

This PR adds a second Spook condition, spook.cooldown, on top of the condition platform introduced in #1386. It passes only when the running automation/script has not triggered within a configured duration (or has never run), replacing the commonly copy-pasted now() - this.attributes.last_triggered > timedelta(...) template. It is implemented purely as a leaf module under ectoplasms/spook/conditions/, so no platform plumbing (condition.py) was touched.

Changes:

• New SpookCondition (cooldown) that reads this.attributes.last_triggered, handling datetime, restored ISO-string, and no-context cases.
• Registers the condition's duration field selector in conditions.yaml and adds its translation entry in en.json.
• Adds full test coverage for discovery, config validation, and each cooldown branch.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
custom_components/spook/ectoplasms/spook/conditions/cooldown.py	New leaf-module condition implementing the per-run cooldown logic and config schema
custom_components/spook/conditions.yaml	Adds the cooldown field metadata with a duration selector for the automation editor
custom_components/spook/translations/en.json	Adds cooldown name/description and duration field strings (alphabetically ordered)
tests/ectoplasms/spook/conditions/test_cooldown.py	Tests discovery, validation, and every cooldown evaluation branch

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.