From 2f5c32bf4a00d054359e548cf7235e05ca8764ab Mon Sep 17 00:00:00 2001
From: Cisphyx <cisphyx@vertex.link>
Date: Fri, 17 Jan 2025 11:37:44 -0500
Subject: [PATCH] Deprecate forms key in Storm command definitions and related
 syn:cmd props (SYN-6596) (#4076)

---
 changes/fce9eb48213f47cd09de69147fc605bd.yaml |  7 +++++++
 docs/docdata/foopkg/foopkg.yml                |  9 ++-------
 synapse/cortex.py                             |  6 ++++++
 synapse/models/syn.py                         |  3 +++
 synapse/tests/test_model_syn.py               | 12 +++++++++---
 5 files changed, 27 insertions(+), 10 deletions(-)
 create mode 100644 changes/fce9eb48213f47cd09de69147fc605bd.yaml

diff --git a/changes/fce9eb48213f47cd09de69147fc605bd.yaml b/changes/fce9eb48213f47cd09de69147fc605bd.yaml
new file mode 100644
index 00000000000..c629916dc99
--- /dev/null
+++ b/changes/fce9eb48213f47cd09de69147fc605bd.yaml
@@ -0,0 +1,7 @@
+---
+desc: The ``forms`` key in Storm package command definitions has been deprecated. The
+  ``cmdinputs`` key may still be used to specify node forms that commands are intended
+  to accept as input.
+prs: []
+type: deprecation
+...
diff --git a/docs/docdata/foopkg/foopkg.yml b/docs/docdata/foopkg/foopkg.yml
index 94a56da1582..2cce4706834 100644
--- a/docs/docdata/foopkg/foopkg.yml
+++ b/docs/docdata/foopkg/foopkg.yml
@@ -38,10 +38,5 @@ commands:
           help: Specify a timeout in seconds.
     cmdconf:
       srcguid: f751f9ad20e75547be230ae1a425fb9f
-    forms:
-      input:
-        - inet:ipv4
-      output:
-        - inet:ipv4
-      nodedata:
-        - [ foodata, file:bytes ]
+    cmdinputs:
+      - form: inet:ipv4
diff --git a/synapse/cortex.py b/synapse/cortex.py
index 759a9d97895..3cae3b4f228 100644
--- a/synapse/cortex.py
+++ b/synapse/cortex.py
@@ -2860,6 +2860,12 @@ async def _normStormPkg(self, pkgdef, validstorm=True):
                 cmdtext = cdef.get('storm')
                 await self.getStormQuery(cmdtext)
 
+            if cdef.get('forms') is not None:
+                name = cdef.get('name')
+                mesg = f"Storm command definition 'forms' key is deprecated and will be removed " \
+                       f"in 3.0.0 (command {name} in package {pkgname})"
+                logger.warning(mesg, extra=await self.getLogExtra(name=name, pkgname=pkgname))
+
         for gdef in pkgdef.get('graphs', ()):
             gdef['iden'] = s_common.guid((pkgname, gdef.get('name')))
             gdef['scope'] = 'power-up'
diff --git a/synapse/models/syn.py b/synapse/models/syn.py
index 8f9f2afc2d2..b8da3bd23a8 100644
--- a/synapse/models/syn.py
+++ b/synapse/models/syn.py
@@ -341,10 +341,13 @@ def getModelDefs(self):
                     ('svciden', ('guid', {'strip': True}), {
                         'doc': 'Storm service iden which provided the package.'}),
                     ('input', ('array', {'type': 'syn:form'}), {
+                        'deprecated': True,
                         'doc': 'The list of forms accepted by the command as input.', 'uniq': True, 'sorted': True, 'ro': True}),
                     ('output', ('array', {'type': 'syn:form'}), {
+                        'deprecated': True,
                         'doc': 'The list of forms produced by the command as output.', 'uniq': True, 'sorted': True, 'ro': True}),
                     ('nodedata', ('array', {'type': 'syn:nodedata'}), {
+                        'deprecated': True,
                         'doc': 'The list of nodedata that may be added by the command.', 'uniq': True, 'sorted': True, 'ro': True}),
                 )),
             ),
diff --git a/synapse/tests/test_model_syn.py b/synapse/tests/test_model_syn.py
index 28565e1425c..c1b5cc67acd 100644
--- a/synapse/tests/test_model_syn.py
+++ b/synapse/tests/test_model_syn.py
@@ -612,10 +612,16 @@ async def test_syn_cmd_runts(self):
                 nodes = await core.nodes('syn:cmd +:package')
                 self.len(0, nodes)
 
-                await core.nodes(f'service.add test {url}')
-                iden = core.getStormSvcs()[0].iden
+                with self.getLoggerStream('synapse.cortex') as stream:
+                    await core.nodes(f'service.add test {url}')
+                    iden = core.getStormSvcs()[0].iden
 
-                await core.nodes('$lib.service.wait(test)')
+                    await core.nodes('$lib.service.wait(test)')
+
+                stream.seek(0)
+                warn = "Storm command definition 'forms' key is deprecated and will be removed " \
+                       "in 3.0.0 (command foobar in package foo)"
+                self.isin(warn, stream.read())
 
                 # check that runt nodes for new commands are created
                 nodes = await core.nodes('syn:cmd +:package')