huge refactor of plugin system

cmdlet/add_tag.py

@@ -22,6 +22,8 @@ SharedArgs = sh.SharedArgs
 normalize_hash = sh.normalize_hash
 parse_tag_arguments = sh.parse_tag_arguments
 expand_tag_groups = sh.expand_tag_groups
+merge_sequences = sh.merge_sequences
+render_tag_value_templates = sh.render_tag_value_templates
 parse_cmdlet_args = sh.parse_cmdlet_args
 collapse_namespace_tag = sh.collapse_namespace_tag
 should_show_help = sh.should_show_help
@@ -524,6 +526,11 @@ class Add_Tag(Cmdlet):
                 "- The source namespace must already exist in the file being tagged.",
                 "- Target namespaces that already have a value are skipped (not overwritten).",
                 "- Use -extract to derive namespaced tags from the current title (title field or title: tag) using a simple template.",
+                "- Use #(namespace) inside a tag value to insert existing values, e.g. add-tag \"title:#(track) - #(series)\".",
+                "- Use angle-bracket transforms for advanced formatting, e.g. add-tag \"code:e<padding(00,#(episode))>\".",
+                "- Current documented transforms include padding, default, replace, and increment.",
+                "- Template examples assume lowercase tag text; case transforms are intentionally not part of the documented syntax.",
+                "- See docs/tag_template_syntax.md for recipe-style examples and the current shared template syntax.",
             ],
             exec=self.run,
         )
@@ -655,6 +662,7 @@ class Add_Tag(Cmdlet):
         # tag ARE provided - apply them to each store-backed result
         total_added = 0
         total_modified = 0
+        unresolved_template_count = 0
 
         store_registry = Store(config, suppress_debug=True)
 
@@ -791,6 +799,13 @@ class Add_Tag(Cmdlet):
                                             if new_tag.lower() not in existing_lower:
                                                 item_tag_to_add.append(new_tag)
 
+                            item_tag_to_add, unresolved_templates = render_tag_value_templates(
+                                item_tag_to_add,
+                                existing_tags=merge_sequences(existing_tag_list, item_tag_to_add, case_sensitive=True),
+                                result=res,
+                            )
+                            unresolved_template_count += len(unresolved_templates)
+
                             item_tag_to_add = collapse_namespace_tag(
                                 item_tag_to_add,
                                 "title",
@@ -962,6 +977,13 @@ class Add_Tag(Cmdlet):
                             if new_tag.lower() not in existing_lower:
                                 item_tag_to_add.append(new_tag)
 
+            item_tag_to_add, unresolved_templates = render_tag_value_templates(
+                item_tag_to_add,
+                existing_tags=merge_sequences(existing_tag_list, item_tag_to_add, case_sensitive=True),
+                result=res,
+            )
+            unresolved_template_count += len(unresolved_templates)
+
             item_tag_to_add = collapse_namespace_tag(
                 item_tag_to_add,
                 "title",
@@ -1109,6 +1131,12 @@ class Add_Tag(Cmdlet):
                 file=sys.stderr,
             )
 
+        if unresolved_template_count > 0:
+            log(
+                f"[add_tag] skipped {unresolved_template_count} tag template(s) with unresolved #(namespace) placeholders",
+                file=sys.stderr,
+            )
+
         return 0