from . import paths
from .profiles import list_profiles, write_text

POWER_PROFILE_TEMPLATE = """# Power profile: __NAME__
#
# Links ONE Anker SOLIX device (read-only data source) to ONE Shelly
# switch channel (the actuator). Rules decide when the Shelly turns on
# or off. The Anker device is never commanded.
#
# Validate before running:
#     __INVOCATION__ run __NAME__ --test
#
# ---------------------------------------------------------------------
# QUICK REFERENCE
# ---------------------------------------------------------------------
# when:      an expression over fields from the Anker device profile.
#            Use field names directly. Allowed: < <= > >= == !=
#            and / or / not, + - * /, and parentheses.
#            Run `__INVOCATION__ fields __SOURCE__` to list every name.
#
# for:       how long the condition must hold continuously before acting.
#            Prevents a passing cloud from toggling the relay. 30s 5m 1h.
#
# then:      target.on, target.off, or none.
#
# priority:  when several rules are ready at once, the highest number
#            wins. Default 0.
#
# notify:    on or off per rule. Omit to inherit the profile default.
#            Only matters when notifications.enabled is true below.
#
# ---------------------------------------------------------------------

name: __NAME__
description: >
  Describe what this profile is for.

enabled: true

poll_interval: 10s

source:
  profile: __SOURCE__
  stale_after: 120s
  on_stale: safe_state

target:
  profile: __TARGET__
  channel: __CHANNEL__

safe_state: on

# SAFETY FLOOR - evaluated before any rule below, and it bypasses the rate
# limits. Once tripped it LATCHES: nothing can turn the target off again until
# the battery climbs back to release_at. Set this whenever the target controls
# charging for the source device, so the battery can never be stranded at 0%.
safety:
  battery_floor:
    at_or_below: 25
    release_at: 45
    then: target.on
    for: 30s
    notify: true
    notify_release: true

# Notifications fire when a rule actually switches the target.
# Channels and credentials live in ../notifications.yaml, not here.
#   solixauto notify-test
notifications:
  enabled: false
  channels: []
  title: "{profile}"
  template: >-
    {source_name} battery {battery_soc}%, solar {pv_total}W.
    {target_name} turned {action}.
  throttle: 5m
  on:
    - action

rules:
__RULES__
limits:
  min_seconds_between_actions: 60
  max_actions_per_hour: 20
"""

RULES_SOLAR = """  - name: grid assist when solar drops
    when: pv_total < 150
    for: 90s
    then: target.on

  - name: release grid when solar recovers
    when: pv_total > 300
    for: 2m
    then: target.off

  - name: emergency charge on low battery
    when: battery_soc <= 15
    for: 30s
    then: target.on
    priority: 100
    notify:
      template: >-
        {source_name} has {battery_soc}% battery remaining.
        {target_name} turned on AC power.
      priority: high
"""

RULES_BATTERY = """  - name: charge when battery is low
    when: battery_soc <= 15
    for: 30s
    then: target.on
    notify:
      template: >-
        {source_name} has {battery_soc}% battery remaining.
        {target_name} turned on AC power.

  - name: stop charging when battery is healthy
    when: battery_soc >= 60
    for: 2m
    then: target.off
"""

RULES_MINIMAL = """  - name: turn on
    when: battery_soc <= 20
    for: 60s
    then: target.on

  - name: turn off
    when: battery_soc >= 50
    for: 60s
    then: target.off
"""

RULE_SETS = {
    "solar": RULES_SOLAR,
    "battery": RULES_BATTERY,
    "minimal": RULES_MINIMAL,
}

README_HEADER = """# Power profiles

> Commands below are written as `solixauto`. If that is not on your PATH, run
> them the same way you ran the tool, for example:
>
>     __INVOCATION__ run <profile> --test
"""

README = """# Power profiles

A power profile is a plain YAML file linking one Anker SOLIX device to one
Shelly switch channel. You can edit it in any text editor.

The Anker device is **read-only**. The engine reads its telemetry and never
sends it a command. The only thing that gets switched is the Shelly.

## Layout

    device-profiles/anker/     generated, one file per Anker device
    device-profiles/shelly/    generated, one file per Shelly device
    power-profiles/            yours, hand-edited
    state/runtime.json         last known target state per profile
    logs/automation.log        action history

## Workflow

    solixauto discover-anker
    solixauto discover-shelly
    solixauto new-profile solar-failover --template solar
    solixauto fields A1782-<serial>
    solixauto run solar-failover --test
    solixauto run solar-failover

## Anatomy of a rule

    - name: grid assist when solar drops
      when: pv_total < 150
      for: 90s
      then: target.on
      priority: 0

`when` is an expression over any field listed in the Anker device profile,
under `readable` or `derived`. `solixauto fields <device>` prints them with
current sample values.

`for` is the dwell time. The condition must stay true for this long before
anything happens. Without it, a cloud passing over your array would cycle the
relay repeatedly.

`then` is `target.on`, `target.off`, or `none`.

`priority` breaks ties. If two rules are ready at the same moment and disagree,
the higher number wins. A low-battery override should outrank normal solar
logic.

## Use a deadband

This is the single most important thing to get right:

    # WRONG - will chatter around 200W
    - when: pv_total < 200
      then: target.on
    - when: pv_total > 200
      then: target.off

    # RIGHT - 150W of deadband between the two
    - when: pv_total < 150
      then: target.on
    - when: pv_total > 300
      then: target.off

`--test` warns when it detects the same threshold used for both directions.

## Useful automations

**Solar failover.** Solar covers the load most of the day; pull from the wall
only when production drops.

    - name: grid assist when solar drops
      when: pv_total < 150
      for: 90s
      then: target.on

    - name: release grid when solar recovers
      when: pv_total > 300
      for: 2m
      then: target.off

**Low-battery charge.** No solar involved.

    - name: charge when battery is low
      when: battery_soc <= 15
      for: 30s
      then: target.on

    - name: stop charging when battery is healthy
      when: battery_soc >= 60
      for: 2m
      then: target.off

**Overnight top-up.** Combine conditions.

    - name: cheap overnight charging
      when: battery_soc < 80 and pv_total < 20
      for: 5m
      then: target.on

**Let solar do the work.** Stop grid charging once the sun is carrying the load
and has spare capacity for the battery. `pv_surplus` is solar minus everything
drawing from the unit, so positive means the surplus is going into the battery.

    - name: solar covers the load, stop grid charging
      when: pv_surplus > 100
      for: 5m
      then: target.off

    - name: solar cannot keep up, fall back to grid
      when: pv_surplus < -100 and battery_soc <= 60
      for: 10m
      then: target.on

The 100W band on either side of zero is the deadband; without it, a load
cycling on and off would flip the relay every few minutes. The SOC condition on
the second rule stops it reaching for the grid on a cloudy afternoon when the
battery is still comfortable.

**Load shedding.** Cut a non-essential circuit when the battery is draining.

    - name: shed load
      when: battery_soc < 30 and ac_input_power == 0
      for: 2m
      then: target.off

**Thermal guard.** Higher priority so it outranks everything else.

    - name: stop charging when hot
      when: temperature >= 45
      for: 60s
      then: target.off
      priority: 200

## Safety settings

`stale_after` and `on_stale` control what happens when telemetry stops
arriving. Rules are never evaluated against stale data.

- `hold` keeps the relay wherever it is. Default and safest.
- `safe_state` drives the relay to the `safe_state:` value.
- `stop` exits the engine.

`limits` is a hard backstop independent of dwell times:

    limits:
      min_seconds_between_actions: 60
      max_actions_per_hour: 20

If a rule somehow oscillates, this caps the damage.

## The safety floor

This is not a rule. It is checked before every rule, it ignores the rate limits,
and once tripped it latches.

    safety:
      battery_floor:
        at_or_below: 25
        release_at: 45
        then: target.on
        for: 30s
        notify: true

Set this whenever the Shelly controls charging for the Anker device itself.
Without it you can deadlock: a rule turns charging off, the battery runs flat,
the device drops off wifi, telemetry goes stale, and nothing ever turns charging
back on.

`release_at` must be meaningfully higher than `at_or_below`. While latched, no
rule can turn the target off, so the battery gets a real recharge instead of
being released at 26% into the same conditions that drained it.

Pair it with a stale policy that fails toward charging:

    source:
      stale_after: 300s
      on_stale: safe_state

    safe_state: on

`--test` warns when no floor is set.

### Floor notifications

The floor notifies on both trip and release, and it does this **even when
`notifications.enabled` is false**. Turning off routine solar chatter should not
silence a battery emergency. All it needs is one enabled channel in
`notifications.yaml`. Push channels get urgent priority, and the throttle is
bypassed.

    safety:
      battery_floor:
        at_or_below: 25
        notify: true
        notify_release: true
        notify_template: >-
          SAFETY: {source_name} battery at {value}. {target_name} turned
          {action} to protect it. Holding until {release}.
        release_template: >-
          {source_name} battery recovered to {value}. Normal rules resumed
          for {target_name}.

Extra fields available in these two templates: `{value}`, `{field}`,
`{threshold}`, `{release}`.

If the floor trips and no channel is configured, the log says so explicitly
rather than failing silently.

## Conflicts with the Shelly's own automation

A Shelly can run schedules, auto-on/auto-off timers, and webhooks entirely on
the device. Those keep running whether or not this engine is running, and they
will fight your rules. A schedule that turns the plug off at 08:00 will undo a
rule that just turned it on, and nothing in the log will explain why.

Check before you rely on anything:

    solixauto conflicts <shelly-profile>

To remove them without leaving the terminal:

    solixauto conflicts <shelly-profile> --fix

That asks before every change and defaults to No. Deletions happen on the
device and cannot be undone from here; you would have to recreate them in the
Shelly app.

Discovery records what it finds, `--test` lists it as notes, and the engine
prints a loud warning at startup if anything is still there.

Remove them in the Shelly app, or accept that the device wins.

One limitation: schedules created as Shelly Cloud **scenes** live in the cloud
rather than on the device, and cannot be seen over local HTTP. If behaviour
still looks wrong after `conflicts` comes back clean, check the app's scenes.

## Notifications

Turn them on in the profile:

    notifications:
      enabled: true
      channels: [ntfy]
      title: "{profile}"
      template: >-
        {source_name} battery {battery_soc}%, solar {pv_total}W.
        {target_name} turned {action}.
      throttle: 5m
      on:
        - action

Then per rule, `notify: on` or `notify: off` to include or exclude it. Omit it
to inherit. A rule can also carry its own wording:

    - name: emergency charge on low battery
      when: battery_soc <= 15
      for: 30s
      then: target.on
      priority: 100
      notify:
        template: >-
          {source_name} has {battery_soc}% battery remaining.
          {target_name} turned on AC power.
        priority: high

### Template fields

Any field from the device profile works, plus:

    {profile}         power profile name
    {rule}            rule that fired
    {condition}       the rule's when expression
    {action}          ON or OFF
    {action_word}     on or off
    {source_name}     Anker device name, falling back to model
    {source_model}    e.g. SOLIX F3000
    {source_serial}
    {target_name}     Shelly device name, falling back to model
    {target_model}
    {target_host}
    {time}

`--test` checks every field name in your templates against the device profile,
so a typo is caught before it ships a message reading `battery ?%`.

### Channels

Credentials live in `../notifications.yaml`, which is created with owner-only
permissions. Power profiles stay free of secrets.

- **ntfy** - recommended. Free, no account. Install the app, pick an
  unguessable topic name, subscribe. Anyone who knows the topic can read your
  alerts, so make it long.
- **pushover** - $5 once per platform. Priority 2 alerts repeat until you
  acknowledge them.
- **email** - SMTP. Gmail requires an App Password.
- **telegram** - free bot.
- **webhook** - Slack, Discord, or generic JSON.
- **desktop** - local notification on the machine running the engine.
  Uses osascript on macOS, notify-send on Linux, PowerShell on Windows.
  Run `solixauto doctor` to see which backend was detected.

The Anker app and the Shelly app cannot receive custom push messages from an
external program, so neither is an option here.

Test a channel:

    solixauto notify-test
    solixauto notify-test --channel ntfy

### Throttling

`throttle` is per rule. An identical repeated message inside the window is
dropped. This is separate from the switching rate limits, so a stuck condition
cannot flood your phone even if the relay is behaving.

### Other events

    on:
      - action
      - stale

`stale` fires once when telemetry stops arriving and is worth enabling if you
depend on the automation.

## Testing

    solixauto run <profile> --test

Validates syntax, checks that every field you reference actually exists on the
device, warns about missing deadbands and short dwell times, connects to both
devices, and prints what each rule would do right now. Nothing is switched.

    solixauto run <profile> --test --offline

Same checks without connecting. Rules are evaluated against the sample values
captured during discovery.
"""


def scaffold_readme():
    destination = paths.POWER_PROFILE_DIR / "README.md"
    header = README_HEADER.replace("__INVOCATION__", paths.invocation())
    body = README.split("\n", 1)[1] if README.startswith("# Power profiles") else README
    write_text(destination, header.rstrip() + "\n" + body)
    return destination


def default_source():
    profiles = list_profiles(paths.ANKER_PROFILE_DIR)
    return profiles[0].name if profiles else "REPLACE-WITH-ANKER-PROFILE.yaml"


def default_target():
    profiles = list_profiles(paths.SHELLY_PROFILE_DIR)
    return profiles[0].name if profiles else "REPLACE-WITH-SHELLY-PROFILE.yaml"


def render(name, source=None, target=None, channel=0, template="solar"):
    rules = RULE_SETS.get(template, RULES_SOLAR)
    output = POWER_PROFILE_TEMPLATE
    for token, value in (
        ("__NAME__", name),
        ("__SOURCE__", source or default_source()),
        ("__TARGET__", target or default_target()),
        ("__CHANNEL__", str(channel)),
        ("__RULES__", rules),
        ("__INVOCATION__", paths.invocation()),
    ):
        output = output.replace(token, value)
    return output


def create(name, source=None, target=None, channel=0, template="solar", force=False):
    paths.ensure_dirs()
    destination = paths.POWER_PROFILE_DIR / f"{name}.yaml"
    if destination.exists() and not force:
        raise FileExistsError(destination)
    write_text(destination, render(name, source, target, channel, template))
    scaffold_readme()
    return destination