Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

14.5 KB
Raw Blame
"""Init step β€” bootstrap a Spec Kit project from within a workflow.

Runs the same scaffolding as ``specify init`` so a workflow can create
(or merge into) a project before driving the rest of the spec-driven
process.  The step invokes the ``init`` command in-process and captures
its exit code and output.
"""

from __future__ import annotations

import os
from typing import Any

from specify_cli._agent_config import (
    SCRIPT_TYPE_CHOICES,
    resolve_default_init_integration,
)
from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
from specify_cli.workflows.expressions import evaluate_expression

#: Valid ``script`` values, derived from the canonical source in _agent_config.
VALID_SCRIPT_TYPES = tuple(SCRIPT_TYPE_CHOICES.keys())

#: Directories the workflow engine may create before steps run.
#: These are excluded from the "non-empty directory" fast-fail check so
#: that ``here: true`` works without requiring ``force: true`` when the
#: only pre-existing content is engine run-state.
_ENGINE_OWNED_DIRS = {".specify"}


class InitStep(StepBase):
    """Bootstrap a project, equivalent to running ``specify init``.

    The step runs the bundled ``specify init`` command non-interactively,
    scaffolding templates, scripts, shared infrastructure, and the
    selected coding agent integration into the target directory.

    Because workflows run unattended, the step defaults to
    ``--ignore-agent-tools`` (skip checks for an installed agent CLI) and
    resolves the integration from the step config, falling back to the
    workflow-level default integration.

    Example YAML::

        - id: bootstrap
          type: init
          here: true
          integration: copilot
          script: sh

    Supported config fields (all optional):

    ``project``
        Project name or path to create.  Use ``"."`` for the current
        directory.  Ignored when ``here`` is truthy.
    ``here``
        Initialize in the target directory instead of creating a new one.
    ``integration``
        Integration key (e.g. ``copilot``).  Defaults to the workflow's
        default integration, then to the resolved default init integration
        (``SPECKIT_INTEGRATION_DEFAULT`` env var, else ``copilot``).
    ``integration_options``
        Extra options for the integration (e.g. ``"--skills"`` or
        ``"--commands-dir .myagent/cmds"``).
    ``script``
        Script type, ``sh``, ``ps``, or ``py``.
    ``force``
        Merge/overwrite without confirmation when the directory is not
        empty.
    ``ignore_agent_tools``
        Skip checks for the coding agent CLI (defaults to ``true``).
    ``preset``
        Preset ID to install during initialization.
    """

    type_key = "init"

    def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
        project = self._resolve(config.get("project"), context)
        here = self._resolve_bool(config.get("here"), context)

        integration = self._resolve(config.get("integration"), context)
        if not integration:
            integration = self._resolve(context.default_integration, context)
        # Apply the same default that specify init uses in non-interactive mode
        # so that output.integration reflects the actual integration used.
        if not integration:
            integration = resolve_default_init_integration()

        integration_options = self._resolve(
            config.get("integration_options"), context
        )
        script = self._resolve(config.get("script"), context)
        preset = self._resolve(config.get("preset"), context)

        force = self._resolve_bool(config.get("force"), context)
        # Workflows run unattended; skip the agent CLI presence check by default.
        # ``config.get(key, True)`` applies that default only when the key is
        # ABSENT: a bare ``ignore_agent_tools:`` in YAML parses to None, which
        # ``_resolve_bool`` then turns into False -- flipping the documented
        # default and re-enabling the agent-CLI presence check this step promises
        # to skip, so an unattended run fails with "Agent Detection Error" for
        # any integration whose CLI is not installed. Normalize an explicit null
        # to the default, mirroring the while/do-while ``max_iterations`` handling.
        raw_ignore_agent_tools = config.get("ignore_agent_tools")
        if raw_ignore_agent_tools is None:
            raw_ignore_agent_tools = True
        ignore_agent_tools = self._resolve_bool(raw_ignore_agent_tools, context)

        argv: list[str] = ["init"]
        if here:
            argv.append("--here")
        elif project:
            argv.append(str(project))
        else:
            # No explicit target β†’ initialize the current directory.
            argv.append(".")

        # Build the full argv (except --force, which may be set implicitly
        # below) so early-return outputs always reflect the complete command.
        if integration:
            argv.extend(["--integration", str(integration)])
        if integration_options:
            argv.extend(["--integration-options", str(integration_options)])
        if script:
            argv.extend(["--script", str(script)])
        if preset:
            argv.extend(["--preset", str(preset)])
        if ignore_agent_tools:
            argv.append("--ignore-agent-tools")

        # When the target is the current directory and ``force`` is not set,
        # ``specify init`` prompts for confirmation if the directory is not
        # empty.  Workflows run unattended (no stdin), so the prompt would
        # abort with a confusing error.  Fail fast with an actionable message.
        # Exception: if the only pre-existing content is engine-owned (e.g.
        # .specify/workflows/runs/), treat it as implicitly empty and auto-add
        # --force so init can proceed unattended.
        targets_current_dir = here or not project or str(project) == "."
        if targets_current_dir and not force:
            base = context.project_root or os.getcwd()
            has_engine_dirs = False
            try:
                with os.scandir(base) as it:
                    for entry in it:
                        if (
                            entry.name in _ENGINE_OWNED_DIRS
                            and entry.is_dir(follow_symlinks=False)
                        ):
                            has_engine_dirs = True
                        else:
                            # Non-engine content found β€” fail fast.
                            has_non_engine_content = True
                            break
                    else:
                        has_non_engine_content = False
            except OSError as exc:
                error_message = (
                    f"Cannot inspect target directory {base!r}: {exc}"
                )
                return StepResult(
                    status=StepStatus.FAILED,
                    output={
                        "argv": argv,
                        "project": project,
                        "here": here,
                        "integration": integration,
                        "integration_options": integration_options,
                        "script": script,
                        "preset": preset,
                        "force": force,
                        "ignore_agent_tools": ignore_agent_tools,
                        "exit_code": 1,
                        "stdout": "",
                        "stderr": error_message,
                    },
                    error=error_message,
                )
            if has_non_engine_content:
                error_message = (
                    f"Target directory {base!r} is not empty. Set "
                    "'force: true' to merge into a non-empty directory."
                )
                return StepResult(
                    status=StepStatus.FAILED,
                    output={
                        "argv": argv,
                        "project": project,
                        "here": here,
                        "integration": integration,
                        "integration_options": integration_options,
                        "script": script,
                        "preset": preset,
                        "force": force,
                        "ignore_agent_tools": ignore_agent_tools,
                        "exit_code": 1,
                        "stdout": "",
                        "stderr": error_message,
                    },
                    error=error_message,
                )
            else:
                # Only engine-owned dirs exist β€” implicitly force so specify
                # init doesn't prompt about the non-empty directory.
                # (Skip if the directory is completely empty β€” no force needed.)
                if has_engine_dirs:
                    force = True

        if force:
            argv.append("--force")

        exit_code, stdout, stderr = self._run_init(argv, context)

        output: dict[str, Any] = {
            "argv": argv,
            "project": project,
            "here": here,
            "integration": integration,
            "integration_options": integration_options,
            "script": script,
            "preset": preset,
            "force": force,
            "ignore_agent_tools": ignore_agent_tools,
            "exit_code": exit_code,
            "stdout": stdout,
            "stderr": stderr,
        }

        if exit_code != 0:
            return StepResult(
                status=StepStatus.FAILED,
                output=output,
                error=(
                    stderr.strip()
                    or stdout.strip()
                    or f"specify init exited with code {exit_code}."
                ),
            )
        return StepResult(status=StepStatus.COMPLETED, output=output)

    @staticmethod
    def _resolve(value: Any, context: StepContext) -> Any:
        """Resolve ``{{ ... }}`` expressions in string config values."""
        if isinstance(value, str) and "{{" in value:
            return evaluate_expression(value, context)
        return value

    @classmethod
    def _resolve_bool(cls, value: Any, context: StepContext) -> bool:
        """Coerce a config value (possibly an expression) to a boolean."""
        resolved = cls._resolve(value, context)
        if isinstance(resolved, str):
            return resolved.strip().lower() in ("true", "1", "yes")
        return bool(resolved)

    @staticmethod
    def _run_init(
        argv: list[str], context: StepContext
    ) -> tuple[int, str, str]:
        """Invoke ``specify init`` in-process and capture exit code/output.

        Runs with the working directory set to ``context.project_root`` so
        that ``--here`` and relative project paths target the right place.
        """
        from typer.testing import CliRunner

        from specify_cli import app

        runner = CliRunner()

        prev_cwd = os.getcwd()
        if context.project_root:
            try:
                os.chdir(context.project_root)
            except OSError as exc:
                return (1, "", f"Cannot enter project root: {exc}")
        try:
            result = runner.invoke(app, argv, catch_exceptions=True)
        finally:
            try:
                os.chdir(prev_cwd)
            except OSError:
                # Best-effort cleanup: avoid masking the init command result
                # if restoring the previous working directory fails.
                pass

        stdout = result.output or ""
        # click >= 8.2 captures stderr separately; older versions mix it into
        # stdout and raise when ``result.stderr`` is accessed.
        try:
            stderr = result.stderr or ""
        except (ValueError, AttributeError):
            # Older Click: stderr is mixed into stdout.  On failure, treat
            # stdout as stderr so workflows can consistently read
            # steps.<id>.output.stderr for error details.
            stderr = stdout if result.exit_code != 0 else ""

        # Record the exception only for an UNEXPECTED crash. ``typer.Exit(n)``
        # -- how ``specify init`` reports every ordinary failure -- surfaces
        # through ``CliRunner`` as ``result.exception = SystemExit(n)``, so this
        # branch used to fire on routine errors too. ``init`` prints its
        # diagnostics through Rich to stdout, leaving ``result.stderr`` empty,
        # so the synthesized "SystemExit: 1" became the whole of ``stderr`` and
        # preempted ``execute``'s ``stderr.strip() or stdout.strip()`` fallback.
        # Every failing init step then reported ``error: 'SystemExit: 1'`` while
        # init's real message -- e.g. the list of valid integrations for a
        # typo'd ``integration:`` -- sat unread in stdout.
        if (
            result.exit_code != 0
            and result.exception is not None
            and not isinstance(result.exception, SystemExit)
        ):
            detail = f"{type(result.exception).__name__}: {result.exception}"
            stderr = f"{stderr}\n{detail}".strip() if stderr else detail
        elif result.exit_code != 0 and not stderr.strip():
            # Ordinary failure with no real stderr: under click >= 8.2 the
            # streams are separate and ``init`` prints its diagnostics through
            # Rich to stdout, so ``result.stderr`` is genuinely empty. Merely
            # dropping the synthesized "SystemExit: 1" would leave
            # ``steps.<id>.output.stderr`` empty -- still no diagnostic for a
            # downstream step to read, and still contrary to the contract above
            # ("treat stdout as stderr so workflows can consistently read
            # steps.<id>.output.stderr for error details"). Carry the captured
            # output across, matching what the older-Click branch already does.
            stderr = stdout.strip()

        return (result.exit_code, stdout, stderr)

    def validate(self, config: dict[str, Any]) -> list[str]:
        errors = super().validate(config)
        script = config.get("script")
        if script is not None and not isinstance(script, str):
            errors.append(
                f"Init step {config.get('id', '?')!r}: 'script' must be a string "
                f"({' or '.join(repr(s) for s in VALID_SCRIPT_TYPES)})."
            )
        elif (
            isinstance(script, str)
            and "{{" not in script
            and script not in VALID_SCRIPT_TYPES
        ):
            errors.append(
                f"Init step {config.get('id', '?')!r}: 'script' must be "
                f"{' or '.join(repr(s) for s in VALID_SCRIPT_TYPES)}."
            )
        return errors