feat(addon): add generic set-field op writing a literal into a chosen field

Author: aadijain

addon/README.md

@@ -39,6 +39,7 @@ The build script is stdlib-only and runs with bare `python`. Install the built `
 | `int-sort` | Sort by rank | `rank` (configurable field) | reorders the deck's new cards |
 | `generate-vocab` | Generate vocab cards | `sentence` | creates new vocab notes for words new to you |
 | `sync-word-status` | Sync word status to vocab store | `word` (required), `word-reading` (optional) | records each word's status in the vocab store (new card -> `seen`, reviewed/suspended -> `learnt`); writes no field |
+| `set-field` | Set field | none (reads no field) | the `target` field, set to a fixed `value` (any string; empty value clears the field; local-only, no backend call) |
 | `clear-formatting` | Clear formatting | the `target` field (default `sentence`) | the same `target` field (strips HTML in place; local-only, no backend call) |
 
 Field-writing ops are idempotent (a value is written only when it differs); most accept an `only_if_empty` option. `int-sort`, `generate-vocab`, and `sync-word-status` operate over the whole target deck, not just a selected subset.

addon/src/jp_utils/ops/registry.py

@@ -12,6 +12,7 @@
 from .int_sort import IntSortOperation
 from .nplus1 import Nplus1SequenceOperation
 from .sentence_furigana import SentenceFuriganaOperation
+from .set_field import SetFieldOperation
 from .sync_status import SyncWordStatusOperation
 from .word_audio import WordAudioOperation
 from .word_definition import WordDefinitionOperation
@@ -30,5 +31,6 @@
     IntSortOperation(),
     GenerateVocabOperation(),
     SyncWordStatusOperation(),
+    SetFieldOperation(),
     ClearFormattingOperation(),
 ]

addon/src/jp_utils/ops/set_field.py

@@ -0,0 +1,62 @@
+"""Set-field operation: write a fixed literal value into a chosen field.
+
+A purely local :class:`FieldOperation` (no backend call) that sets one alias to a
+constant the user types. It is deliberately datatype-agnostic - it sets *any*
+field with a plain string, so the same op covers Lapis' boolean toggle flags
+(``'true'`` / empty for ``IsClickCard`` etc., see T-34), a category label, or any
+other fixed value; there is no separate "boolean" kind.
+
+Both halves come from params: ``target`` picks the alias to write (param-driven,
+so :meth:`io_spec` validates and displays whichever field is chosen) and ``value``
+is the literal to write. Neither has a default - the op does nothing useful until
+the user configures both. An *explicit* empty ``value`` clears the target (needed
+to unset a boolean flag); a ``value`` that was never set (``None``) writes nothing.
+The shared ``only_if_empty`` toggle still applies (skip notes whose target is
+already populated). Reading no input alias, it applies to every note in the deck.
+"""
+
+from ..client import BackendClient
+from ..config import ALIASES
+from .base import ONLY_IF_EMPTY, FieldOperation, IOSpec, ParamSpec
+
+
+class SetFieldOperation(FieldOperation):
+    key = "set-field"
+    label = "Set field"
+    # No static input/output aliases: the target is param-driven (see io_spec), and
+    # the op reads no field so it applies to every note.
+    params_spec = (
+        ParamSpec(
+            "target",
+            "Target field",
+            "choice",
+            choices=ALIASES,
+            description="The field to write the value into.",
+        ),
+        ParamSpec(
+            "value",
+            "Value",
+            "text",
+            description="The literal value to set. Leave empty to clear the field.",
+        ),
+        ONLY_IF_EMPTY,
+    )
+
+    def io_spec(self, params: dict | None = None) -> IOSpec:
+        target = (params or {}).get("target")
+        return IOSpec(outputs=(target,) if target else ())
+
+    def io_display(self, params: dict | None = None) -> str:
+        params = params or {}
+        target = params.get("target")
+        out = "{" + target + "}" if target else "{}"
+        value = params.get("value")
+        literal = "(unset)" if value is None else f'"{value}"'
+        return f"{out} ← {literal}"
+
+    def compute(
+        self, client: BackendClient, sources: list[dict[str, str]], params: dict | None = None
+    ) -> list[str | None]:
+        value = (params or {}).get("value")
+        # An unconfigured value (never set) writes nothing; an explicit "" clears.
+        return [value] * len(sources)

addon/tests/test_ops_set_field.py

@@ -0,0 +1,85 @@
+"""Tests for the set-field operation (local literal write into a chosen field)."""
+
+from jp_utils.ops import ConfiguredOp, NoteFields, plan_operations, resolve_params
+from jp_utils.ops.set_field import SetFieldOperation
+
+
+def test_io_spec_targets_the_chosen_alias():
+    op = SetFieldOperation()
+    assert op.io_spec({"target": "definition"}).outputs == ("definition",)
+    # No required inputs - the op applies to every note.
+    assert op.io_spec({"target": "definition"}).required_inputs == ()
+    # Unconfigured target writes nothing.
+    assert op.io_spec().outputs == ()
+
+
+def test_no_param_defaults_for_target_and_value():
+    op = SetFieldOperation()
+    params = resolve_params(op, None)
+    assert params["target"] is None
+    assert params["value"] is None
+    # only_if_empty keeps its shared default.
+    assert params["only_if_empty"] is True
+
+
+def test_applicable_to_every_note_regardless_of_fields():
+    op = SetFieldOperation()
+    assert op.applicable({}, {"target": "frequency", "value": "x"}) is True
+
+
+def test_compute_repeats_the_value():
+    op = SetFieldOperation()
+    sources = [{}, {"word": "a"}]
+    assert op.compute(None, sources, {"value": "true"}) == ["true", "true"]
+
+
+def test_compute_unconfigured_value_writes_nothing():
+    op = SetFieldOperation()
+    # value never set -> None per source, which plan_operations skips.
+    assert op.compute(None, [{}], {"target": "frequency"}) == [None]
+
+
+def test_plan_writes_value_to_target():
+    op = SetFieldOperation()
+    notes = [NoteFields(note_id=1, fields={"frequency": ""})]
+    params = {"target": "frequency", "value": "true", "only_if_empty": False}
+    plans = plan_operations(None, [ConfiguredOp(op, params)], notes)
+    [update] = plans[0].updates
+    assert update.alias == "frequency"
+    assert update.value == "true"
+
+
+def test_plan_idempotent_when_already_equal():
+    op = SetFieldOperation()
+    notes = [NoteFields(note_id=1, fields={"frequency": "true"})]
+    params = {"target": "frequency", "value": "true", "only_if_empty": False}
+    assert plan_operations(None, [ConfiguredOp(op, params)], notes) == []
+
+
+def test_explicit_empty_value_clears_the_field():
+    op = SetFieldOperation()
+    notes = [NoteFields(note_id=1, fields={"frequency": "true"})]
+    params = {"target": "frequency", "value": "", "only_if_empty": False}
+    [plan] = plan_operations(None, [ConfiguredOp(op, params)], notes)
+    [update] = plan.updates
+    assert update.value == ""
+
+
+def test_only_if_empty_skips_populated_target():
+    op = SetFieldOperation()
+    notes = [NoteFields(note_id=1, fields={"frequency": "old"})]
+    params = {"target": "frequency", "value": "new", "only_if_empty": True}
+    assert plan_operations(None, [ConfiguredOp(op, params)], notes) == []
+
+
+def test_unconfigured_target_writes_nothing():
+    op = SetFieldOperation()
+    notes = [NoteFields(note_id=1, fields={"frequency": "x"})]
+    params = {"value": "v", "only_if_empty": False}
+    assert plan_operations(None, [ConfiguredOp(op, params)], notes) == []
+
+
+def test_io_display_shows_target_and_literal():
+    op = SetFieldOperation()
+    assert op.io_display({"target": "frequency", "value": "true"}) == '{frequency} ← "true"'
+    assert op.io_display({"target": "frequency"}) == "{frequency} ← (unset)"