π« Toolkit to help you get started with SDD or any other process!
"""Junie integration (JetBrains)."""
from ..base import MarkdownIntegration
from ..manifest import IntegrationManifest
import re
from collections.abc import Mapping, Sequence
from pathlib import Path
from typing import Any
# Note injected into hook sections so Junie maps dot-notation command
# names (from extensions.yml) to the hyphenated slash commands it uses.
_HOOK_COMMAND_NOTE = (
"- When constructing slash commands from hook command names, "
"replace dots (`.`) with hyphens (`-`). "
"For example, `speckit.git.commit` β `/speckit-git-commit`.\n"
)
def format_junie_command_name(cmd_name: str) -> str:
"""Convert command name to Junie-compatible hyphenated format.
Junie does not allow dots inside of slash-commands.
This function converts dot-notation command names to hyphenated format.
The function is idempotent: already-formatted names are returned unchanged.
Examples:
>>> format_junie_command_name("plan")
'speckit-plan'
>>> format_junie_command_name("speckit.plan")
'speckit-plan'
>>> format_junie_command_name("speckit.git.commit")
'speckit-git-commit'
Args:
cmd_name: Command name in dot notation (speckit.foo.bar),
hyphenated format (speckit-foo-bar), or plain name (foo)
Returns:
Hyphenated command name with 'speckit-' prefix
"""
cmd_name = cmd_name.replace(".", "-")
if not cmd_name.startswith("speckit-"):
cmd_name = f"speckit-{cmd_name}"
return cmd_name
class JunieIntegration(MarkdownIntegration):
key = "junie"
config = {
"name": "Junie",
"folder": ".junie/",
"commands_subdir": "commands",
"install_url": "https://junie.jetbrains.com/",
"requires_cli": True,
}
registrar_config = {
"dir": ".junie/commands",
"format": "markdown",
"args": "$ARGUMENTS",
"extension": ".md",
"inject_name": True,
"format_name": format_junie_command_name,
"invoke_separator": "-",
}
multi_install_safe = True
invoke_separator = "-"
def command_filename(self, template_name: str) -> str:
return format_junie_command_name(template_name) + ".md"
def build_command_invocation(self, command_name: str, args: str = "") -> str:
"""Junie installs hyphenated slash-commands (``/speckit-<name>``), so the
dispatch invocation must match. The inherited MarkdownIntegration default
builds the dotted ``/speckit.<name>``, which references a command Junie
never registered. Reuse the same hyphenation as command_filename /
the injected frontmatter name (see ``format_junie_command_name``),
mirroring the forge integration.
"""
invocation = "/" + format_junie_command_name(command_name)
if args:
invocation = f"{invocation} {args}"
return invocation
def process_template(self, *args, **kwargs):
"""Ensure shared templates render Junie command references with hyphens."""
kwargs.setdefault("invoke_separator", self.invoke_separator)
return super().process_template(*args, **kwargs)
@staticmethod
def _inject_hook_command_note(content: str) -> str:
"""Insert a dot-to-hyphen note before each hook output instruction.
Targets the line ``- For each executable hook, output the following``
and inserts the note on the line before it, matching its indentation.
Skips if the note is already present.
"""
if "replace dots" in content:
return content
def repl(m: re.Match[str]) -> str:
indent = m.group(1)
instruction = m.group(2)
# ``eol`` is empty when the regex matched via ``$`` because the
# instruction was the final line of a file with no trailing
# newline. Default to ``\n`` so the note never collapses onto
# the same line as the instruction.
eol = m.group(3) or "\n"
return (
indent
+ _HOOK_COMMAND_NOTE.rstrip("\n")
+ eol
+ indent
+ instruction
+ eol
)
return re.sub(
r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
repl,
content,
)
@staticmethod
def _rewrite_handoff_references(content: str) -> str:
"""Replace dot-notation agent references in handoffs with hyphens."""
return re.sub(
r"(?m)^(\s*agent:\s*)(speckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*)",
lambda m: f"{m.group(1)}{format_junie_command_name(m.group(2))}",
content,
)
def post_process_command_content(self, content: str) -> str:
"""Apply Junie-specific transformations to command content.
Overrides the ``IntegrationBase`` hook of the same name so that
``CommandRegistrar.register_commands()`` (which dispatches to
``post_process_command_content``) applies these transforms to
extension/preset command files too, not just core commands.
"""
updated = self._inject_hook_command_note(content)
updated = self._rewrite_handoff_references(updated)
return updated
def setup(
self,
project_root: Path,
manifest: IntegrationManifest,
parsed_options: dict[str, Any] | None = None,
**opts: Any,
) -> list[Path]:
"""Install Junie commands and apply post-processing transformations."""
created = super().setup(project_root, manifest, parsed_options, **opts)
# Post-process generated command files
dest_dir = self.commands_dest(project_root).resolve()
for path in created:
# Only touch .md files under the commands directory
try:
path.resolve().relative_to(dest_dir)
except ValueError:
continue
if path.suffix != ".md":
continue
content_bytes = path.read_bytes()
content = content_bytes.decode("utf-8")
updated = self.post_process_command_content(content)
if updated != content:
from .._file_changes import write_bytes
write_bytes(path, updated.encode("utf-8"))
self.record_file_in_manifest(path, project_root, manifest)
return created
def build_exec_args(
self,
prompt: str,
*,
model: str | None = None,
output_json: bool = True,
integration_args: Sequence[str] | None = None,
integration_options: Mapping[str, Any] | None = None,
project_root: Path | None = None,
) -> list[str] | None:
"""Build CLI arguments for non-interactive ``junie`` execution.
``MarkdownIntegration``'s default passes the prompt as ``-p <prompt>``,
but Junie's ``-p`` is ``--project <path>``, so the prompt would be
taken as the project directory and no task would be given. Junie
takes a non-interactive task as a positional argument or ``--task``.
"""
self.validate_runtime_config(integration_args, integration_options)
if not self.config or not self.config.get("requires_cli"):
return None
args = [self._resolve_executable(), "--task", prompt]
self._apply_extra_args_env_var(args)
if model:
args.extend(["--model", model])
if output_json:
args.extend(["--output-format", "json"])
return args