Merge pull request #16 from jniu-atlas/issue/DEPLOY-2389-Add-Tracking-Env-Var-To-Forge-Skill-all

Stamp ATL_FORGE_ATTRIBUTION_SKILL_NAME on Forge CLI invocations

Author: dpeach-jpg

skills/forge-app-builder/SKILL.md

@@ -24,6 +24,7 @@ namespace: cloud
 5. **Always ask the user to choose** when multiple options exist (developer spaces, sites) — never pick on their behalf
 6. **Always ask the user for their Atlassian site URL during installation** — never try to discover it from other apps, environment variables, or any other source
 7. **Always run the deploy script for deploy and install** — do not give the user only manual `forge deploy` / `forge install` commands as the primary outcome; run `scripts.deploy_forge_app.py` yourself
+8. **Set `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder` on `forge` commands run for this skill** — prefix `forge` invocations with this env var: ones you run in the shell (e.g. `forge developer-spaces list`, `forge lint`) **and the interactive `forge create` command you hand the user as a fallback**. The bundled scripts set it automatically; other commands shown in this skill omit it for brevity — add it when you run them. The only exclusions are `forge login` and `forge tunnel` (user-run auth / live-dev commands).
 
 ## MCP Server Prerequisites
 
@@ -70,7 +71,7 @@ Install in order: Node.js first (required for npm), then Forge CLI, then login.
 ### Step 1: Discover Developer Spaces
 
 ```bash
-forge developer-spaces list --json
+ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder forge developer-spaces list --json
 ```
 
 ### Step 2: Ask User to Choose Developer Space
@@ -188,7 +189,7 @@ Example response when it fails:
 ```
 forge create needs an interactive terminal. Please run:
 
-  forge create --template jira-dashboard-gadget my-app-name
+  ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder forge create --template jira-dashboard-gadget my-app-name
 
 Once created, let me know and I'll help customize it.
 ```

skills/forge-app-builder/scripts/create_forge_app.py

@@ -15,12 +15,16 @@
 
 # Relative imports — scripts/ is a package; run as python -m scripts.create_forge_app from skill dir
 from . import list_templates as list_templates_module
+from .forge_env import forge_env
+
+# Environment for every Forge CLI invocation this script spawns.
+_FORGE_ENV = forge_env("forge-app-builder")
 
 def validate_prerequisites():
     """Check if Forge CLI and Node.js are available"""
     try:
-        subprocess.run(['forge', '--version'], capture_output=True, check=True)
-        subprocess.run(['node', '-v'], capture_output=True, check=True)
+        subprocess.run(['forge', '--version'], capture_output=True, check=True, env=_FORGE_ENV)
+        subprocess.run(['node', '-v'], capture_output=True, check=True, env=_FORGE_ENV)
         return True
     except (subprocess.CalledProcessError, FileNotFoundError):
         return False
@@ -59,7 +63,7 @@ def discover_dev_spaces():
     try:
         result = subprocess.run(
             ['forge', 'developer-spaces', 'list', '--json'],
-            capture_output=True, text=True, timeout=30,
+            capture_output=True, text=True, timeout=30, env=_FORGE_ENV,
         )
         if result.returncode != 0:
             print(f"⚠️  forge developer-spaces list failed: {result.stderr.strip()}")
@@ -139,7 +143,7 @@ def create_app(template, app_name, output_dir=None, dev_space_id=None):
         print(f"\n📦 Creating Forge app: {app_name}")
         print(f"📋 Template: {template}")
         print(f"📂 Location: {cwd}")
-        result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+        result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, env=_FORGE_ENV)
 
         if result.returncode != 0:
             stderr = result.stderr.strip()
@@ -191,7 +195,7 @@ def main():
             print("\n📋 Please create a developer space at:")
             print("   https://developer.atlassian.com/console/")
             print("\nThen run this script again, or use 'forge create' interactively:")
-            print(f"   forge create --template {args.template} {args.name}")
+            print(f"   ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder forge create --template {args.template} {args.name}")
             sys.exit(1)
 
         # Step 1b: Ask user which dev space to use

skills/forge-app-builder/scripts/deploy_forge_app.py

@@ -22,6 +22,11 @@
 import time
 from pathlib import Path
 
+from .forge_env import forge_env
+
+# Environment for every Forge CLI invocation this script spawns.
+_FORGE_ENV = forge_env("forge-app-builder")
+
 
 class Colors:
     HEADER = '\033[95m'
@@ -66,7 +71,8 @@ def run_command(cmd, cwd=None, capture_output=True, check=True):
             cwd=cwd,
             capture_output=capture_output,
             text=True,
-            check=check
+            check=check,
+            env=_FORGE_ENV,
         )
         return result
     except subprocess.CalledProcessError as e:

skills/forge-app-builder/scripts/forge_env.py

@@ -0,0 +1,66 @@
+"""Environment helper for spawning the Forge CLI.
+
+The Forge CLI reads a reserved ``ATL_FORGE_ATTRIBUTION_*`` namespace from
+its environment and forwards every key in it to the backend. This helper
+returns an environment mapping with the skill identifier stamped in, so
+that every ``forge`` command a skill spawns carries it.
+
+The same namespace is open-ended, so the helper supports arbitrary
+wildcard fields beyond the skill name:
+
+* ``extra=`` stamps additional keys programmatically, e.g.
+  ``forge_env("forge-app-builder", extra={"run_id": "abc"})`` →
+  ``ATL_FORGE_ATTRIBUTION_RUN_ID=abc``.
+* any ``ATL_FORGE_ATTRIBUTION_*`` var already present in the environment
+  (e.g. set by the agent host) is preserved and forwarded as-is.
+
+Values the helper stamps follow the CLI's contract — short tokens
+matching ``[A-Za-z0-9._-]`` and at most 128 characters; values that
+don't match are dropped silently rather than raising.
+"""
+
+import os
+import re
+
+_ATTRIBUTION_PREFIX = "ATL_FORGE_ATTRIBUTION_"
+_VALUE_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+_MAX_LEN = 128
+
+
+def _is_valid_value(value):
+    """True if ``value`` satisfies the Forge CLI value contract."""
+    return (
+        isinstance(value, str)
+        and 0 < len(value) <= _MAX_LEN
+        and _VALUE_RE.match(value) is not None
+    )
+
+
+def forge_env(skill_name, extra=None, base=None):
+    """Return an environment dict for spawning the Forge CLI.
+
+    Starts from a copy of the current process environment (or ``base`` if
+    provided) and stamps ``ATL_FORGE_ATTRIBUTION_SKILL_NAME=<skill_name>``.
+
+    ``extra`` may supply additional ``ATL_FORGE_ATTRIBUTION_*`` fields as a
+    mapping of unprefixed keys to values (e.g. ``{"SESSION_ID": "abc"}`` →
+    ``ATL_FORGE_ATTRIBUTION_SESSION_ID=abc``). Keys are upper-cased and
+    prefixed; entries whose value fails validation are skipped.
+
+    Any ``ATL_FORGE_ATTRIBUTION_*`` vars already in the source environment
+    are left untouched, so wildcard fields set by the caller's environment
+    pass through to the CLI unchanged.
+    """
+    # Copying the source env preserves ambient ATL_FORGE_ATTRIBUTION_* vars.
+    env = dict(os.environ if base is None else base)
+
+    fields = {"SKILL_NAME": skill_name}
+    if extra:
+        fields.update(extra)
+
+    for key, value in fields.items():
+        if not _is_valid_value(value):
+            continue
+        env[_ATTRIBUTION_PREFIX + key.upper()] = value
+
+    return env

skills/forge-app-builder/tests/test_create_forge_app.py

@@ -203,6 +203,24 @@ def test_runs_from_parent_directory(self, mock_prereqs, mock_validate, mock_run)
         call_kwargs = mock_run.call_args[1]
         self.assertEqual(call_kwargs.get("cwd"), "/parent")
 
+    @patch("scripts.create_forge_app.subprocess.run")
+    @patch("scripts.create_forge_app.validate_template", return_value=(True, None))
+    @patch("scripts.create_forge_app.validate_prerequisites", return_value=True)
+    def test_stamps_skill_name_env_var(self, mock_prereqs, mock_validate, mock_run):
+        """forge create must carry the skill-name attribution env var."""
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+        with patch("scripts.create_forge_app.os.path.isdir", return_value=True), \
+             patch("scripts.create_forge_app.os.path.exists", return_value=False):
+            cfa.create_app(
+                "jira-issue-panel-ui-kit", "my-app",
+                output_dir="/tmp", dev_space_id="abc-123",
+            )
+
+        env = mock_run.call_args[1].get("env")
+        self.assertIsNotNone(env)
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
 
 if __name__ == "__main__":
     unittest.main()

skills/forge-app-builder/tests/test_deploy_forge_app.py

@@ -176,6 +176,15 @@ def test_raises_on_failure(self, mock_run):
         with self.assertRaises(subprocess.CalledProcessError):
             dfa.run_command("bad-cmd")
 
+    @patch("scripts.deploy_forge_app.subprocess.run")
+    def test_stamps_skill_name_env_var(self, mock_run):
+        """Every command run by the deploy script carries the attribution env var."""
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        dfa.run_command("forge deploy")
+        env = mock_run.call_args[1].get("env")
+        self.assertIsNotNone(env)
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
 
 if __name__ == "__main__":
     unittest.main()

skills/forge-app-builder/tests/test_forge_env.py

@@ -0,0 +1,72 @@
+"""Tests for scripts/forge_env.py"""
+import unittest
+
+from scripts.forge_env import forge_env
+
+
+class TestForgeEnv(unittest.TestCase):
+
+    def test_stamps_skill_name(self):
+        env = forge_env("forge-app-builder", base={})
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
+    def test_preserves_base_environment(self):
+        env = forge_env("forge-app-builder", base={"PATH": "/usr/bin", "HOME": "/home/x"})
+        self.assertEqual(env["PATH"], "/usr/bin")
+        self.assertEqual(env["HOME"], "/home/x")
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
+    def test_defaults_to_current_process_environment(self):
+        # Without an explicit base, the current environment is copied (and not mutated).
+        import os
+        env = forge_env("forge-app-builder")
+        self.assertIn("ATL_FORGE_ATTRIBUTION_SKILL_NAME", env)
+        self.assertNotIn("ATL_FORGE_ATTRIBUTION_SKILL_NAME", os.environ)
+
+    def test_extra_keys_are_upper_cased_and_prefixed(self):
+        env = forge_env("forge-app-builder", extra={"session_id": "abc123"}, base={})
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SESSION_ID"], "abc123")
+
+    def test_multiple_wildcard_extras_are_all_stamped(self):
+        env = forge_env(
+            "forge-app-builder",
+            extra={"run_id": "r1", "session_id": "s1"},
+            base={},
+        )
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_RUN_ID"], "r1")
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SESSION_ID"], "s1")
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
+    def test_ambient_wildcard_vars_pass_through(self):
+        # Wildcard vars the agent host already set must reach the CLI untouched.
+        env = forge_env(
+            "forge-app-builder",
+            base={"ATL_FORGE_ATTRIBUTION_RUN_ID": "host-run-42", "PATH": "/usr/bin"},
+        )
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_RUN_ID"], "host-run-42")
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
+    def test_invalid_extra_value_is_dropped(self):
+        env = forge_env("forge-app-builder", extra={"run_id": "bad value!"}, base={})
+        self.assertNotIn("ATL_FORGE_ATTRIBUTION_RUN_ID", env)
+        self.assertEqual(env["ATL_FORGE_ATTRIBUTION_SKILL_NAME"], "forge-app-builder")
+
+    def test_over_length_value_is_dropped(self):
+        env = forge_env("x" * 129, base={})
+        self.assertNotIn("ATL_FORGE_ATTRIBUTION_SKILL_NAME", env)
+
+    def test_invalid_charset_value_is_dropped(self):
+        env = forge_env("bad name!", base={})
+        self.assertNotIn("ATL_FORGE_ATTRIBUTION_SKILL_NAME", env)
+
+    def test_empty_value_is_dropped(self):
+        env = forge_env("", base={})
+        self.assertNotIn("ATL_FORGE_ATTRIBUTION_SKILL_NAME", env)
+
+    def test_non_string_value_is_dropped(self):
+        env = forge_env(None, base={})  # type: ignore[arg-type]
+        self.assertNotIn("ATL_FORGE_ATTRIBUTION_SKILL_NAME", env)
+
+
+if __name__ == "__main__":
+    unittest.main()

skills/forge-connector/SKILL.md

@@ -39,6 +39,7 @@ Builds a `graph:connector` Forge app that ingests external data into Atlassian's
 10. **`function` declarations belong under `modules`** — In `manifest.yml`, `function:` is a key under `modules:`, not a top-level key. Placing it at the top level causes a lint error.
 11. **`formConfiguration` uses `form` array with `type: header`** — Do NOT use `fields:` or `beforeYouBegin:`. The correct format uses `form: [{ key, type: header, title, description, properties: [...] }]`.
 12. **Scopes are `read/write/delete:object:jira`** — Use `read:object:jira`, `write:object:jira`, `delete:object:jira`. The scopes `read:graph:teamwork` and `write:graph:teamwork` are invalid and will fail `forge lint`.
+13. **Set `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector` on `forge` commands run for this skill** — prefix `forge` invocations with this env var: ones you run in the shell (e.g. `forge lint`, `forge logs`, `forge deploy`) **and the interactive `forge create` command you hand the user as a fallback**. The bundled scripts set it automatically; other commands shown in this skill omit it for brevity — add it when you run them. The only exclusions are `forge login` and `forge tunnel` (user-run auth / live-dev commands).
 
 ## MCP Prerequisites
 
@@ -72,7 +73,7 @@ Tell the user to run `forge login` in their terminal if not authenticated.
 ```
 Tell the user:
   cd <parent-directory>
-  forge create --template blank <app-name>
+  ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector forge create --template blank <app-name>
 
   When prompted, select a Developer Space and let it complete.
   Come back when done.

skills/forge-connector/scripts/forge_env.py

@@ -0,0 +1,66 @@
+"""Environment helper for spawning the Forge CLI.
+
+The Forge CLI reads a reserved ``ATL_FORGE_ATTRIBUTION_*`` namespace from
+its environment and forwards every key in it to the backend. This helper
+returns an environment mapping with the skill identifier stamped in, so
+that every ``forge`` command a skill spawns carries it.
+
+The same namespace is open-ended, so the helper supports arbitrary
+wildcard fields beyond the skill name:
+
+* ``extra=`` stamps additional keys programmatically, e.g.
+  ``forge_env("forge-connector", extra={"run_id": "abc"})`` →
+  ``ATL_FORGE_ATTRIBUTION_RUN_ID=abc``.
+* any ``ATL_FORGE_ATTRIBUTION_*`` var already present in the environment
+  (e.g. set by the agent host) is preserved and forwarded as-is.
+
+Values the helper stamps follow the CLI's contract — short tokens
+matching ``[A-Za-z0-9._-]`` and at most 128 characters; values that
+don't match are dropped silently rather than raising.
+"""
+
+import os
+import re
+
+_ATTRIBUTION_PREFIX = "ATL_FORGE_ATTRIBUTION_"
+_VALUE_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+_MAX_LEN = 128
+
+
+def _is_valid_value(value):
+    """True if ``value`` satisfies the Forge CLI value contract."""
+    return (
+        isinstance(value, str)
+        and 0 < len(value) <= _MAX_LEN
+        and _VALUE_RE.match(value) is not None
+    )
+
+
+def forge_env(skill_name, extra=None, base=None):
+    """Return an environment dict for spawning the Forge CLI.
+
+    Starts from a copy of the current process environment (or ``base`` if
+    provided) and stamps ``ATL_FORGE_ATTRIBUTION_SKILL_NAME=<skill_name>``.
+
+    ``extra`` may supply additional ``ATL_FORGE_ATTRIBUTION_*`` fields as a
+    mapping of unprefixed keys to values (e.g. ``{"SESSION_ID": "abc"}`` →
+    ``ATL_FORGE_ATTRIBUTION_SESSION_ID=abc``). Keys are upper-cased and
+    prefixed; entries whose value fails validation are skipped.
+
+    Any ``ATL_FORGE_ATTRIBUTION_*`` vars already in the source environment
+    are left untouched, so wildcard fields set by the caller's environment
+    pass through to the CLI unchanged.
+    """
+    # Copying the source env preserves ambient ATL_FORGE_ATTRIBUTION_* vars.
+    env = dict(os.environ if base is None else base)
+
+    fields = {"SKILL_NAME": skill_name}
+    if extra:
+        fields.update(extra)
+
+    for key, value in fields.items():
+        if not _is_valid_value(value):
+            continue
+        env[_ATTRIBUTION_PREFIX + key.upper()] = value
+
+    return env