π« Toolkit to help you get started with SDD or any other process!
fix(opencode): use commands/ directory (plural) to match OpenCode docs (#2453)
Marcus Burghardt9732a4d09230
diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.pyindex 4d78d5ac4..a1be34dcc 100644--- a/src/specify_cli/agents.py+++ b/src/specify_cli/agents.py@@ -438,6 +438,7 @@ class CommandRegistrar:source_dir: Path,project_root: Path,context_note: str = None,+ _resolved_dir: Path = None,) -> List[str]:"""Register commands for a specific agent.@@ -448,6 +449,10 @@ class CommandRegistrar:source_dir: Directory containing command source filesproject_root: Path to project rootcontext_note: Custom context comment for markdown output+ _resolved_dir: Pre-resolved command directory (internal use+ only β avoids a second ``_resolve_agent_dir`` call and+ duplicate deprecation warnings when invoked from+ ``register_commands_for_all_agents``).Returns:List of registered command names@@ -460,7 +465,9 @@ class CommandRegistrar:raise ValueError(f"Unsupported agent: {agent_name}")agent_config = self.AGENT_CONFIGS[agent_name]- commands_dir = project_root / agent_config["dir"]+ commands_dir = _resolved_dir or self._resolve_agent_dir(+ agent_name, agent_config, project_root,+ )commands_dir.mkdir(parents=True, exist_ok=True)registered = []@@ -639,6 +646,40 @@ class CommandRegistrar:CommandRegistrar._ensure_inside(prompt_file, prompts_dir)prompt_file.write_text(f"---\nagent: {cmd_name}\n---\n", encoding="utf-8")+ @staticmethod+ def _resolve_agent_dir(+ agent_name: str,+ agent_config: dict[str, Any],+ project_root: Path,+ ) -> Path:+ """Return the agent command directory, falling back to legacy_dir.++ When the canonical directory (``agent_config["dir"]``) does not+ exist but a ``legacy_dir`` is configured and present on disk,+ returns the legacy path and emits a deprecation warning advising+ the user to upgrade.++ Integrations that do not declare ``legacy_dir`` get the canonical+ path unconditionally β no fallback, no warning.+ """+ agent_dir = project_root / agent_config["dir"]+ if not agent_dir.exists():+ legacy = agent_config.get("legacy_dir")+ if legacy:+ legacy_dir = project_root / legacy+ if legacy_dir.exists():+ import warnings++ warnings.warn(+ f"Found legacy '{legacy}' directory for "+ f"{agent_name}. Run 'specify integration "+ f"upgrade {agent_name}' to migrate to "+ f"'{agent_config['dir']}'.",+ stacklevel=3,+ )+ return legacy_dir+ return agent_dir+def register_commands_for_all_agents(self,commands: List[Dict[str, Any]],@@ -663,7 +704,9 @@ class CommandRegistrar:self._ensure_configs()for agent_name, agent_config in self.AGENT_CONFIGS.items():- agent_dir = project_root / agent_config["dir"]+ agent_dir = self._resolve_agent_dir(+ agent_name, agent_config, project_root,+ )if agent_dir.exists():try:@@ -674,6 +717,7 @@ class CommandRegistrar:source_dir,project_root,context_note=context_note,+ _resolved_dir=agent_dir,)if registered:results[agent_name] = registered@@ -711,7 +755,9 @@ class CommandRegistrar:for agent_name, agent_config in self.AGENT_CONFIGS.items():if agent_config.get("extension") == "/SKILL.md":continue- agent_dir = project_root / agent_config["dir"]+ agent_dir = self._resolve_agent_dir(+ agent_name, agent_config, project_root,+ )if agent_dir.exists():try:registered = self.register_commands(@@ -721,6 +767,7 @@ class CommandRegistrar:source_dir,project_root,context_note=context_note,+ _resolved_dir=agent_dir,)if registered:results[agent_name] = registered@@ -733,6 +780,11 @@ class CommandRegistrar:) -> None:"""Remove previously registered command files from agent directories.+ When a ``legacy_dir`` is configured, files are removed from+ *both* the canonical and the legacy directory so that orphaned+ commands left behind after an ``integration upgrade`` are+ cleaned up as well.+Args:registered_commands: Dict mapping agent names to command name listsproject_root: Path to project root@@ -743,24 +795,39 @@ class CommandRegistrar:continueagent_config = self.AGENT_CONFIGS[agent_name]- commands_dir = project_root / agent_config["dir"]+ commands_dir = self._resolve_agent_dir(+ agent_name, agent_config, project_root,+ )++ # Collect all directories to clean: canonical (or resolved+ # legacy) plus the legacy dir if it exists separately.+ dirs_to_clean = [commands_dir]+ legacy = agent_config.get("legacy_dir")+ if legacy:+ legacy_dir = project_root / legacy+ if legacy_dir.exists() and legacy_dir != commands_dir:+ dirs_to_clean.append(legacy_dir)for cmd_name in cmd_names:output_name = self._compute_output_name(agent_name, cmd_name, agent_config)- cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"- if cmd_file.exists():- cmd_file.unlink()- # For SKILL.md agents each command lives in its own subdirectory- # (e.g. .agents/skills/speckit-ext-cmd/SKILL.md). Remove the- # parent dir when it becomes empty to avoid orphaned directories.- parent = cmd_file.parent- if parent != commands_dir and parent.exists():- try:- parent.rmdir() # no-op if dir still has other files- except OSError:- pass+ for target_dir in dirs_to_clean:+ cmd_file = (+ target_dir / f"{output_name}{agent_config['extension']}"+ )+ if cmd_file.exists():+ cmd_file.unlink()+ # For SKILL.md agents each command lives in its own+ # subdirectory (e.g. .agents/skills/speckit-ext-cmd/+ # SKILL.md). Remove the parent dir when it becomes+ # empty to avoid orphaned directories.+ parent = cmd_file.parent+ if parent != target_dir and parent.exists():+ try:+ parent.rmdir()+ except OSError:+ passif agent_name == "copilot":prompt_file = (diff --git a/src/specify_cli/integrations/opencode/__init__.py b/src/specify_cli/integrations/opencode/__init__.pyindex 17db2bd11..4fa9c724a 100644--- a/src/specify_cli/integrations/opencode/__init__.py+++ b/src/specify_cli/integrations/opencode/__init__.py@@ -8,12 +8,13 @@ class OpencodeIntegration(MarkdownIntegration):config = {"name": "opencode","folder": ".opencode/",- "commands_subdir": "command",+ "commands_subdir": "commands","install_url": "https://opencode.ai","requires_cli": True,}registrar_config = {- "dir": ".opencode/command",+ "dir": ".opencode/commands",+ "legacy_dir": ".opencode/command","format": "markdown","args": "$ARGUMENTS","extension": ".md",diff --git a/tests/integrations/test_integration_opencode.py b/tests/integrations/test_integration_opencode.pyindex 427fd1516..ba2d15711 100644--- a/tests/integrations/test_integration_opencode.py+++ b/tests/integrations/test_integration_opencode.py@@ -1,6 +1,10 @@"""Tests for OpencodeIntegration."""+import warnings++from specify_cli.agents import CommandRegistrarfrom specify_cli.integrations import get_integration+from specify_cli.integrations.manifest import IntegrationManifestfrom .test_integration_base_markdown import MarkdownIntegrationTests@@ -8,8 +12,8 @@ from .test_integration_base_markdown import MarkdownIntegrationTestsclass TestOpencodeIntegration(MarkdownIntegrationTests):KEY = "opencode"FOLDER = ".opencode/"- COMMANDS_SUBDIR = "command"- REGISTRAR_DIR = ".opencode/command"+ COMMANDS_SUBDIR = "commands"+ REGISTRAR_DIR = ".opencode/commands"CONTEXT_FILE = "AGENTS.md"def test_build_exec_args_uses_run_command_dispatch(self):@@ -57,3 +61,140 @@ class TestOpencodeIntegration(MarkdownIntegrationTests):args = integration.build_exec_args("explain this repository", output_json=False)assert args == ["opencode", "run", "explain this repository"]++ def test_registrar_config_has_legacy_dir(self):+ integration = get_integration(self.KEY)+ assert integration.registrar_config["legacy_dir"] == ".opencode/command"++ def test_legacy_dir_extension_registration(self, tmp_path):+ """Extensions register in legacy .opencode/command/ with a warning."""+ # Seed a legacy project with only .opencode/command/+ legacy_dir = tmp_path / ".opencode" / "command"+ legacy_dir.mkdir(parents=True)+ (legacy_dir / "speckit.specify.md").write_text("# existing", encoding="utf-8")++ # Create a source command file for the registrar+ src_dir = tmp_path / "_ext_src"+ src_dir.mkdir()+ (src_dir / "myext.md").write_text(+ "---\ndescription: test\n---\n# ext command", encoding="utf-8",+ )++ registrar = CommandRegistrar()+ commands = [{"name": "speckit.myext", "file": "myext.md"}]++ with warnings.catch_warnings(record=True) as caught:+ warnings.simplefilter("always")+ results = registrar.register_commands_for_all_agents(+ commands, "test-ext", src_dir, tmp_path,+ )++ # Should have registered in the legacy directory+ assert "opencode" in results+ assert (legacy_dir / "speckit.myext.md").exists()+ # Canonical directory should NOT have been created+ assert not (tmp_path / ".opencode" / "commands").exists()+ # Should have emitted a deprecation warning+ opencode_warnings = [+ w for w in caught+ if "legacy" in str(w.message) and "opencode" in str(w.message)+ ]+ assert len(opencode_warnings) == 1, (+ f"Expected exactly 1 legacy-dir warning, got {len(opencode_warnings)}"+ )+ assert "specify integration upgrade" in str(opencode_warnings[0].message)++ def test_legacy_dir_unregister(self, tmp_path):+ """Unregister finds commands in legacy .opencode/command/ dir."""+ legacy_dir = tmp_path / ".opencode" / "command"+ legacy_dir.mkdir(parents=True)+ cmd_file = legacy_dir / "speckit.myext.md"+ cmd_file.write_text("# ext command", encoding="utf-8")++ registrar = CommandRegistrar()++ with warnings.catch_warnings(record=True):+ warnings.simplefilter("always")+ registrar.unregister_commands(+ {"opencode": ["speckit.myext"]}, tmp_path,+ )++ assert not cmd_file.exists()++ def test_unregister_cleans_legacy_when_both_dirs_exist(self, tmp_path):+ """Unregister removes files from legacy dir even when canonical exists."""+ # Set up both canonical and legacy dirs+ canonical_dir = tmp_path / ".opencode" / "commands"+ canonical_dir.mkdir(parents=True)+ legacy_dir = tmp_path / ".opencode" / "command"+ legacy_dir.mkdir(parents=True)++ # Place a command file in the legacy dir (orphaned after upgrade)+ legacy_cmd = legacy_dir / "speckit.myext.md"+ legacy_cmd.write_text("# orphaned ext command", encoding="utf-8")+ # Place the same command in the canonical dir (current)+ canonical_cmd = canonical_dir / "speckit.myext.md"+ canonical_cmd.write_text("# ext command", encoding="utf-8")++ registrar = CommandRegistrar()++ with warnings.catch_warnings(record=True):+ warnings.simplefilter("always")+ registrar.unregister_commands(+ {"opencode": ["speckit.myext"]}, tmp_path,+ )++ # Both files should be removed+ assert not canonical_cmd.exists(), (+ "Command file in canonical dir should be removed"+ )+ assert not legacy_cmd.exists(), (+ "Orphaned command file in legacy dir should also be removed"+ )++ def test_canonical_dir_preferred_over_legacy(self, tmp_path):+ """When both dirs exist, canonical .opencode/commands/ is used."""+ legacy_dir = tmp_path / ".opencode" / "command"+ legacy_dir.mkdir(parents=True)+ canonical_dir = tmp_path / ".opencode" / "commands"+ canonical_dir.mkdir(parents=True)+ (canonical_dir / "speckit.specify.md").write_text("# cmd", encoding="utf-8")++ # Create a source command file for the registrar+ src_dir = tmp_path / "_ext_src"+ src_dir.mkdir()+ (src_dir / "myext.md").write_text(+ "---\ndescription: test\n---\n# ext command", encoding="utf-8",+ )++ registrar = CommandRegistrar()+ commands = [{"name": "speckit.myext", "file": "myext.md"}]++ with warnings.catch_warnings(record=True) as caught:+ warnings.simplefilter("always")+ results = registrar.register_commands_for_all_agents(+ commands, "test-ext", src_dir, tmp_path,+ )++ # Should register in canonical dir, not legacy+ assert "opencode" in results+ assert (canonical_dir / "speckit.myext.md").exists()+ assert not (legacy_dir / "speckit.myext.md").exists()+ # No legacy warning when canonical dir exists+ opencode_warnings = [+ w for w in caught+ if "legacy" in str(w.message) and "opencode" in str(w.message)+ ]+ assert len(opencode_warnings) == 0++ def test_setup_writes_to_canonical_dir(self, tmp_path):+ """New installs always write to .opencode/commands/ (plural)."""+ integration = get_integration(self.KEY)+ manifest = IntegrationManifest(self.KEY, tmp_path)+ integration.setup(tmp_path, manifest)++ canonical = tmp_path / ".opencode" / "commands"+ legacy = tmp_path / ".opencode" / "command"+ assert canonical.is_dir()+ assert not legacy.exists()+ assert any(canonical.glob("speckit.*.md"))diff --git a/tests/integrations/test_integration_subcommand.py b/tests/integrations/test_integration_subcommand.pyindex 5163f98db..e36067b3c 100644--- a/tests/integrations/test_integration_subcommand.py+++ b/tests/integrations/test_integration_subcommand.py@@ -762,7 +762,7 @@ class TestIntegrationSwitch:assert result.exit_code == 0, result.output# Git extension commands should exist for opencode- opencode_git_feature = project / ".opencode" / "command" / "speckit.git.feature.md"+ opencode_git_feature = project / ".opencode" / "commands" / "speckit.git.feature.md"assert opencode_git_feature.exists(), "Git extension command should exist for opencode"# Old kimi extension skills should be removed@@ -837,7 +837,7 @@ class TestIntegrationSwitch:])assert result.exit_code == 0, result.output- opencode_git_feature = project / ".opencode" / "command" / "speckit.git.feature.md"+ opencode_git_feature = project / ".opencode" / "commands" / "speckit.git.feature.md"assert opencode_git_feature.exists(), "Git extension command should exist for opencode"assert not copilot_git_feature.exists(), "Old Copilot extension skill should be removed"@@ -858,7 +858,7 @@ class TestIntegrationSwitch:result = _run_in_project(project, ["extension", "disable", "git"])assert result.exit_code == 0, result.output- opencode_git_feature = project / ".opencode" / "command" / "speckit.git.feature.md"+ opencode_git_feature = project / ".opencode" / "commands" / "speckit.git.feature.md"assert opencode_git_feature.exists(), "Disabled extension command remains until integration switch"result = _run_in_project(project, [@@ -1168,6 +1168,49 @@ class TestIntegrationUpgrade:assert data["integration"] == "gemini"assert "/speckit.plan" in template.read_text(encoding="utf-8")+ def test_upgrade_migrates_opencode_legacy_dir(self, tmp_path):+ """Upgrade moves OpenCode commands from .opencode/command/ to .opencode/commands/."""+ project = _init_project(tmp_path, "opencode")++ # Simulate a legacy project: rename commands/ back to command/+ canonical = project / ".opencode" / "commands"+ legacy = project / ".opencode" / "command"+ assert canonical.is_dir(), "init should have created .opencode/commands/"+ canonical.rename(legacy)+ assert legacy.is_dir()+ assert not canonical.exists()++ # Patch the manifest to reflect old paths (command/ not commands/)+ manifest_path = project / ".specify" / "integrations" / "opencode.manifest.json"+ manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))+ patched_files = {}+ for path, info in manifest_data.get("files", {}).items():+ patched_files[path.replace(".opencode/commands/", ".opencode/command/")] = info+ manifest_data["files"] = patched_files+ manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")++ old_commands = sorted(legacy.glob("speckit.*.md"))+ assert len(old_commands) > 0, "Legacy dir should have speckit command files"++ result = _run_in_project(project, [+ "integration", "upgrade", "opencode",+ "--script", "sh",+ "--force",+ ])+ assert result.exit_code == 0, f"upgrade failed: {result.output}"++ # New commands in canonical dir+ assert canonical.is_dir(), ".opencode/commands/ should exist after upgrade"+ new_commands = sorted(canonical.glob("speckit.*.md"))+ assert len(new_commands) > 0, "Commands should exist in .opencode/commands/"++ # Stale files removed from legacy dir+ remaining = list(legacy.glob("speckit.*.md"))+ assert len(remaining) == 0, (+ f"Legacy .opencode/command/ should have no speckit files after upgrade, "+ f"found: {[f.name for f in remaining]}"+ )+# ββ Full lifecycle βββββββββββββββββββββββββββββββββββββββββββββββββββ