feat(tools): idf.py extension - added interface version

Author: Marek Fiala

docs/en/api-guides/tools/idf-py.rst

@@ -333,6 +333,7 @@ An extension file defines an ``action_extensions`` function which returns additi
               print(f"About to execute {len(tasks)} task(s): {[t.name for t in tasks]}")
 
       return {
+          "version": "1",
           "global_options": [
               {
                   "names": ["--detail", "-d"],
@@ -362,8 +363,9 @@ An extension file defines an ``action_extensions`` function which returns additi
 Extension API Reference
 -----------------------
 
-The ``action_extensions`` function takes arguments ``base_actions`` (all currently registered commands) and ``project_path`` (absolute project directory) and returns a dictionary with up to three keys:
+The ``action_extensions`` function takes arguments ``base_actions`` (all currently registered commands) and ``project_path`` (absolute project directory) and returns a dictionary with up to four keys:
 
+- ``version``: A string representing the interface version of the extension. Currently, the API version is ``1``. **This key is mandatory** and must be provided.
 - ``global_options``: A list of options available globally for all commands. Each option is a dictionary with fields such as ``names``, ``help``, ``type``, ``is_flag``, ``scope``, etc.
 - ``global_action_callbacks``: A list of functions called once before any task execution. Each global action callback function accepts three arguments:
 

tools/idf_py_actions/tools.py

@@ -768,6 +768,12 @@ def _check_action_conflicts(name: str, action: dict[str, Any], existing_identifi
     if not custom_actions:
         return merged_actions
 
+    if not custom_actions.get('version'):
+        raise AttributeError(
+            'Attribute "version" is required in custom extension. '
+            'Please update your extension dictionary to contain the "version" attribute.'
+        )
+
     existing_identifiers = _get_all_action_identifiers(merged_actions['actions'])
     for name, action in custom_actions.get('actions', {}).items():
         try:

tools/test_build_system/test_idf_extension.py

@@ -23,6 +23,7 @@ def test_extension_action(target_name, ctx, args):
         return 0
 
     return {{
+        'version': '1',
         'global_options': [{global_options}],
         'actions': {{
             {actions}
@@ -211,6 +212,26 @@ def some_function():
     ret = idf_py('--help')
     assert "has no attribute 'action_extensions'" in ret.stderr
 
+    idf_ext_py.write_text(
+        textwrap.dedent(
+            TEST_EXT_TEMPLATE.format(
+                suffix='component extension',
+                global_options='',
+                actions="""'test-component-action': {
+                'callback': test_extension_action,
+                'help': 'Test action from component extension'
+            }""",
+            )
+        )
+    )
+    replace_in_file(
+        idf_ext_py,
+        "'version': '1',",
+        '\n',
+    )
+    ret = idf_py('--help')
+    assert 'Attribute "version" is required in custom extension.' in ret.stderr
+
 
 # ----------- Test cases for entry point extension -----------