feat(familiars): icon field on /api/v1/familiars (read + write)

[BunsDev]

Summary

The daemon now owns the full read+write story for a familiar's glyph.

Adds an optional icon field to ~/.coven/familiars.toml, served at GET /api/v1/familiars and writable via a new PUT /api/v1/familiars/{id}/icon. The Cave's glyph picker (OpenCoven/coven-cave#6, already merged) can stop writing only to Cave-local localStorage and start persisting picks back to the user's TOML — surviving across devices, reinstalls, and other Cave surfaces.

Schema

[[familiar]]
id = "cody"
icon = "ph:lightning-fill"   # Phosphor icon

[[familiar]]
id = "kitten"
icon = "🐈‍⬛"                # emoji literal

The ph: prefix is the wire discriminator. Both shapes round-trip through one field, so the daemon stays neutral about which kind a user wants.

Endpoints

Method	Path	Body	Status	Behavior
GET	/api/v1/familiars	—	200	FamiliarDto[] now includes icon when present, omitted when absent
PUT	/api/v1/familiars/{id}/icon	{ "icon": "ph:cat-fill" }	200	Insert or replace the icon
PUT	/api/v1/familiars/{id}/icon	{ "icon": null } or {} or empty body	200	Clear the field
PUT	/api/v1/familiars/{id}/icon	{ "icon": [1,2,3] }	400	Reject non-string/non-null
PUT	/api/v1/familiars/{id}/icon	any	404	Unknown familiar id — error.code = "familiar_not_found"

Whitespace-only values normalize to None so a " " icon can't escape as an empty glyph.

Write safety

• cockpit_sources::write_familiar_icon() does the edit via toml_edit so existing field order, comments, and surrounding whitespace are preserved.
• Atomic write: serialize to .familiars.toml.tmp in the same directory, then rename over the target — POSIX-atomic on the same filesystem and Windows-safe. A crash mid-write can leave the temp file behind but never a half-written familiars.toml.

Tests (12 new)

cockpit_sources::tests (6):

• read_familiars_carries_icon_field_for_both_shapes — TOML round-trip for ph: names, emoji literals, whitespace, absent
• familiar_dto_skips_serializing_absent_icon — wire shape contract
• write_familiar_icon_inserts_when_absent_and_preserves_other_fields — surrounding fields + comments survive
• write_familiar_icon_replaces_existing_value
• write_familiar_icon_clears_field_when_value_is_none
• write_familiar_icon_treats_whitespace_as_clear
• write_familiar_icon_returns_not_found_for_unknown_id
• write_familiar_icon_leaves_no_tempfile_on_success — atomic-rename hygiene

api::tests (6):

• put_familiar_icon_updates_existing_value
• put_familiar_icon_inserts_when_absent — also asserts the other familiar's icon stays untouched
• put_familiar_icon_clears_when_null
• put_familiar_icon_returns_404_for_unknown_id
• put_familiar_icon_rejects_non_string_icon
• put_familiar_icon_with_empty_body_clears

Pre-existing read_familiars_parses_toml_entries extended to also assert icon = None on fixtures that don't set it.

Dependency

Adds toml_edit = "0.22" (with serde feature) for write-side formatting preservation. toml = "1.1" (read-only) stays.

Test plan

• cargo fmt --check -p coven-cli clean (the first CI run failed on this — fixed)
• cargo test -p coven-cli all green, all 12 new tests pass
• cargo check -p coven-cli clean
• After merge, set icon = "ph:cat-fill" on a familiar in local ~/.coven/familiars.toml, restart the daemon, hit GET /api/v1/familiars, confirm the field appears
• Same flow but via PUT — curl -X PUT --unix-socket "$COVEN_SOCK" http://x/api/v1/familiars/cody/icon -d '{"icon":"ph:cat-fill"}' — confirm the TOML is updated and surrounding formatting is preserved

Follow-up

Cave-side daemon-writer: extend cave-glyph-overrides.ts to also PUT to this endpoint when the user picks a glyph (with localStorage as a fast-path mirror that stays valid if the daemon is offline). One small PR on coven-cave.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.