fix: harden codex skill frontmatter and script fallback

Author: RbBtSn0w

src/specify_cli/agents.py

@@ -176,6 +176,9 @@ def parse_frontmatter(content: str) -> tuple[dict, str]:
         except yaml.YAMLError:
             frontmatter = {}
 
+        if not isinstance(frontmatter, dict):
+            frontmatter = {}
+
         return frontmatter, body
 
     @staticmethod
@@ -280,6 +283,9 @@ def render_skill_command(
         frontmatter shape used elsewhere in the project instead of the
         original command frontmatter.
         """
+        if not isinstance(frontmatter, dict):
+            frontmatter = {}
+
         if agent_name == "codex":
             body = self._resolve_codex_skill_placeholders(frontmatter, body, project_root)
 
@@ -308,19 +314,39 @@ def _resolve_codex_skill_placeholders(frontmatter: dict, body: str, project_root
         except ImportError:
             return body
 
-        script_variant = load_init_options(project_root).get("script")
-        if script_variant not in {"sh", "ps"}:
-            return body.replace("{ARGS}", "$ARGUMENTS").replace("__AGENT__", "codex")
+        if not isinstance(frontmatter, dict):
+            frontmatter = {}
 
         scripts = frontmatter.get("scripts", {}) or {}
         agent_scripts = frontmatter.get("agent_scripts", {}) or {}
+        if not isinstance(scripts, dict):
+            scripts = {}
+        if not isinstance(agent_scripts, dict):
+            agent_scripts = {}
 
-        script_command = scripts.get(script_variant)
+        script_variant = load_init_options(project_root).get("script")
+        if script_variant not in {"sh", "ps"}:
+            fallback_order = []
+            if "sh" in scripts or "sh" in agent_scripts:
+                fallback_order.append("sh")
+            if "ps" in scripts or "ps" in agent_scripts:
+                fallback_order.append("ps")
+
+            for key in scripts:
+                if key not in fallback_order:
+                    fallback_order.append(key)
+            for key in agent_scripts:
+                if key not in fallback_order:
+                    fallback_order.append(key)
+
+            script_variant = fallback_order[0] if fallback_order else None
+
+        script_command = scripts.get(script_variant) if script_variant else None
         if script_command:
             script_command = script_command.replace("{ARGS}", "$ARGUMENTS")
             body = body.replace("{SCRIPT}", script_command)
 
-        agent_script_command = agent_scripts.get(script_variant)
+        agent_script_command = agent_scripts.get(script_variant) if script_variant else None
         if agent_script_command:
             agent_script_command = agent_script_command.replace("{ARGS}", "$ARGUMENTS")
             body = body.replace("{AGENT_SCRIPT}", agent_script_command)

tests/test_extensions.py

@@ -642,6 +642,21 @@ def test_parse_frontmatter_no_frontmatter(self):
         assert frontmatter == {}
         assert body == content
 
+    def test_parse_frontmatter_non_mapping_returns_empty_dict(self):
+        """Non-mapping YAML frontmatter should not crash downstream renderers."""
+        content = """---
+- item1
+- item2
+---
+
+# Command body
+"""
+        registrar = CommandRegistrar()
+        frontmatter, body = registrar.parse_frontmatter(content)
+
+        assert frontmatter == {}
+        assert "Command body" in body
+
     def test_render_frontmatter(self):
         """Test rendering frontmatter to YAML."""
         frontmatter = {
@@ -899,6 +914,69 @@ def test_codex_skill_alias_frontmatter_matches_alias_name(self, project_dir, tem
         assert "name: speckit-alias.cmd" in primary.read_text()
         assert "name: speckit-shortcut" in alias.read_text()
 
+    def test_codex_skill_registration_uses_fallback_script_variant_without_init_options(
+        self, project_dir, temp_dir
+    ):
+        """Codex placeholder substitution should still work without init-options.json."""
+        import yaml
+
+        ext_dir = temp_dir / "ext-script-fallback"
+        ext_dir.mkdir()
+        (ext_dir / "commands").mkdir()
+
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "ext-script-fallback",
+                "name": "Script fallback",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.fallback.plan",
+                        "file": "commands/plan.md",
+                    }
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        (ext_dir / "commands" / "plan.md").write_text(
+            """---
+description: "Fallback scripted command"
+scripts:
+  sh: scripts/bash/setup-plan.sh --json "{ARGS}"
+  ps: scripts/powershell/setup-plan.ps1 -Json
+agent_scripts:
+  sh: scripts/bash/update-agent-context.sh __AGENT__
+---
+
+Run {SCRIPT}
+Then {AGENT_SCRIPT}
+"""
+        )
+
+        # Intentionally do NOT create .specify/init-options.json
+        skills_dir = project_dir / ".agents" / "skills"
+        skills_dir.mkdir(parents=True)
+
+        manifest = ExtensionManifest(ext_dir / "extension.yml")
+        registrar = CommandRegistrar()
+        registrar.register_commands_for_agent("codex", manifest, ext_dir, project_dir)
+
+        skill_file = skills_dir / "speckit-fallback.plan" / "SKILL.md"
+        assert skill_file.exists()
+
+        content = skill_file.read_text()
+        assert "{SCRIPT}" not in content
+        assert "{AGENT_SCRIPT}" not in content
+        assert 'scripts/bash/setup-plan.sh --json "$ARGUMENTS"' in content
+        assert "scripts/bash/update-agent-context.sh codex" in content
+
     def test_register_commands_for_copilot(self, extension_dir, project_dir):
         """Test registering commands for Copilot agent with .agent.md extension."""
         # Create .github/agents directory (Copilot project)