github/github-spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-07-03 12:28:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add init workflow step to bootstrap projects like specify init (#2838)

Browse Source 
* Initial plan

* Add init workflow step to bootstrap projects like `specify init`

* Address review: simplify stderr capture and extract VALID_SCRIPT_TYPES

* Address review: fail fast on non-empty dir, stdout fallback, README force fix

* Populate exit_code/stdout/stderr in non-empty-dir fast-fail

* fix: address three unresolved review comments in InitStep

- Use `with os.scandir(...)` context manager so the iterator is always
  closed even when `any()` short-circuits, preventing file-descriptor
  leaks in long-running workflow runs.
- Guard `os.chdir(prev_cwd)` in the `finally` block with a try/except
  so an `OSError` (e.g. directory deleted) doesn't bypass returning
  the captured `StepResult`.
- Reject non-string `script` values in `validate()` with a clear error
  message, rather than silently passing them through to become
  `--script True` at runtime.

* Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

* fix: remove no_git and branch_numbering options removed upstream

The --no-git and --branch-numbering flags were removed from `specify init`
on main. Update InitStep to drop these unsupported config fields and fix
tests accordingly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: address review — integration defaults, integration_options, engine-owned dirs

- Apply DEFAULT_INIT_INTEGRATION fallback when neither step config nor
  workflow context provides an integration, so output.integration always
  reflects the actual integration used.
- Add integration_options config field to support --integration-options
  passthrough (required for generic integration and --skills mode).
- Exclude .specify/ from the non-empty directory fast-fail check so that
  here: true works when the engine has already created its run-state
  directory before steps execute.
- Note: mix_stderr=False is not needed — Click 8.2+ captures stderr
  separately by default and the existing try/except handles access.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: implicitly add --force when only engine-owned dirs exist

When the workflow engine creates .specify/workflows/runs/ before steps
execute, the directory is technically non-empty. Previously, specify init
would prompt for confirmation (hanging in unattended mode) unless the
user explicitly set force: true. Now the step detects that only
engine-owned directories (.specify/) are present and implicitly adds
--force so init proceeds without user interaction.

Also fixes the test to exercise the implicit-force path rather than
passing force: True explicitly (which bypassed the check entirely).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: derive VALID_SCRIPT_TYPES from shared constant, fail fast on OSError, include all resolved fields in output

- Derive VALID_SCRIPT_TYPES from SCRIPT_TYPE_CHOICES in _agent_config
  so the valid set cannot drift from the specify init CLI.
- Fail fast with a clear error when os.scandir() raises OSError (e.g.
  permission denied) instead of silently treating the directory as empty.
- Include preset, force, and ignore_agent_tools in all output dicts
  (both fast-fail and normal paths) for consistent interpolation and
  debugging downstream.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: populate stderr from stdout on older Click, fix force comment wording

- When Click does not expose result.stderr (older versions where stderr
  is mixed into stdout), use stdout as stderr on non-zero exit so
  workflows can consistently read steps.<id>.output.stderr for errors.
- Update README inline comment for force: wording to say 'when target
  directory already exists' rather than 'non-empty directory', matching
  the actual specify init behavior for the project: form.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: build argv flags before early returns, use any() for dir scan

- Move argv flag-building (--integration, --script, --preset,
  --ignore-agent-tools) before the non-empty-dir and OSError early
  returns so output['argv'] always reflects the complete command.
- --force is appended after the check since it may be set implicitly.
- Replace list comprehension with any() generator expression to
  short-circuit without allocating a full list of DirEntry objects.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: only treat .specify as engine-owned when it is a real directory

A file or symlink named .specify should not be excluded from the
non-empty check. Use entry.is_dir(follow_symlinks=False) to ensure
only an actual directory is considered engine-owned content.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: guard implicit force for engine dirs only, fix integration fallback order

- Only set implicit --force when engine-owned directories (.specify/)
  are actually present. A completely empty directory no longer gets
  --force added unnecessarily.
- Fix integration resolution precedence: resolve step config expression
  first, then fall back to workflow default (also resolved), then to
  DEFAULT_INIT_INTEGRATION. Previously, a step expression resolving to
  falsy would bypass the workflow default entirely.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Co-authored-by: Manfred Riem <mnriem@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Copilot
2026-06-17 11:46:51 -05:00
committed by GitHub
parent bc5bf55258
commit 00bff788c9
6 changed files with 500 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/specify_cli/workflows/__init__.py
View File

@@ -50,6 +50,7 @@ def _register_builtin_steps() -> None:
from .steps.fan_out import FanOutStep
from .steps.gate import GateStep
from .steps.if_then import IfThenStep
from .steps.init import InitStep
from .steps.prompt import PromptStep
from .steps.shell import ShellStep
from .steps.switch import SwitchStep
@@ -61,6 +62,7 @@ def _register_builtin_steps() -> None:
_register_step(FanOutStep())
_register_step(GateStep())
_register_step(IfThenStep())
_register_step(InitStep())
_register_step(PromptStep())
_register_step(ShellStep())
_register_step(SwitchStep())

2
src/specify_cli/workflows/engine.py
View File

@@ -94,7 +94,7 @@ def _get_valid_step_types() -> set[str]:
if STEP_REGISTRY:
return set(STEP_REGISTRY.keys())
return {
"command", "shell", "prompt", "gate", "if",
"command", "shell", "prompt", "gate", "if", "init",
"switch", "while", "do-while", "fan-out", "fan-in",
}

309
src/specify_cli/workflows/steps/init/__init__.py Normal file
View File

@@ -0,0 +1,309 @@
"""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 DEFAULT_INIT_INTEGRATION, SCRIPT_TYPE_CHOICES
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 ``DEFAULT_INIT_INTEGRATION``.
``integration_options``
Extra options for the integration (e.g. ``"--skills"`` or
``"--commands-dir .myagent/cmds"``).
``script``
Script type, ``sh`` or ``ps``.
``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 = 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.
ignore_agent_tools = self._resolve_bool(
config.get("ignore_agent_tools", True), 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 ""
if result.exit_code != 0 and result.exception is not None:
detail = f"{type(result.exception).__name__}: {result.exception}"
stderr = f"{stderr}\n{detail}".strip() if stderr else detail
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

167
tests/test_workflows.py
View File

@@ -104,7 +104,7 @@ class TestStepRegistry:
expected = {
"command", "shell", "prompt", "gate", "if", "switch",
"while", "do-while", "fan-out", "fan-in",
"while", "do-while", "fan-out", "fan-in", "init",
}
assert expected.issubset(set(STEP_REGISTRY.keys()))
@@ -1049,6 +1049,171 @@ def _force_gate_stdin(monkeypatch, *, tty: bool):
monkeypatch.setattr(gate_module, "sys", _FakeSys(tty=tty))
class TestInitStep:
"""Test the init step type."""
def test_builds_here_argv_and_bootstraps(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
ctx = StepContext(
project_root=str(tmp_path), default_integration="copilot"
)
config = {"id": "bootstrap", "here": True, "script": "sh"}
result = step.execute(config, ctx)
assert result.status == StepStatus.COMPLETED
assert result.output["exit_code"] == 0
argv = result.output["argv"]
assert argv[0] == "init"
assert "--here" in argv
assert "--integration" in argv and "copilot" in argv
assert "--ignore-agent-tools" in argv
assert (tmp_path / ".specify").is_dir()
def test_default_integration_falls_back_to_workflow_default(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
ctx = StepContext(
project_root=str(tmp_path), default_integration="copilot"
)
result = step.execute(
{"id": "bootstrap", "here": True, "script": "sh"}, ctx
)
assert result.status == StepStatus.COMPLETED
assert result.output["integration"] == "copilot"
def test_project_name_creates_subdirectory(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
ctx = StepContext(
project_root=str(tmp_path), default_integration="copilot"
)
result = step.execute(
{
"id": "bootstrap",
"project": "demo",
"script": "sh",
},
ctx,
)
assert result.status == StepStatus.COMPLETED
assert (tmp_path / "demo" / ".specify").is_dir()
def test_invalid_integration_fails(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
ctx = StepContext(project_root=str(tmp_path))
result = step.execute(
{
"id": "bootstrap",
"here": True,
"integration": "no-such-agent",
"script": "sh",
},
ctx,
)
assert result.status == StepStatus.FAILED
assert result.output["exit_code"] != 0
assert result.error is not None
def test_non_empty_current_dir_without_force_fails_fast(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
(tmp_path / "existing.txt").write_text("data")
step = InitStep()
ctx = StepContext(
project_root=str(tmp_path), default_integration="copilot"
)
result = step.execute(
{"id": "bootstrap", "here": True, "script": "sh"},
ctx,
)
assert result.status == StepStatus.FAILED
assert "force: true" in (result.error or "")
assert not (tmp_path / ".specify").exists()
def test_engine_owned_dirs_do_not_trigger_non_empty_check(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
# Simulate the engine creating its run-state directory before steps run
(tmp_path / ".specify" / "workflows" / "runs" / "abc123").mkdir(
parents=True
)
step = InitStep()
ctx = StepContext(
project_root=str(tmp_path), default_integration="copilot"
)
result = step.execute(
{"id": "bootstrap", "here": True, "script": "sh"},
ctx,
)
assert result.status == StepStatus.COMPLETED
# Verify --force was implicitly added
assert "--force" in result.output["argv"]
def test_default_integration_when_none_provided(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
# No default_integration on context either
ctx = StepContext(project_root=str(tmp_path))
result = step.execute(
{"id": "bootstrap", "here": True, "script": "sh"},
ctx,
)
assert result.status == StepStatus.COMPLETED
assert result.output["integration"] == "copilot"
def test_integration_options_passed_through(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
ctx = StepContext(
project_root=str(tmp_path), default_integration="copilot"
)
result = step.execute(
{
"id": "bootstrap",
"here": True,
"script": "sh",
"integration": "copilot",
"integration_options": "--skills",
},
ctx,
)
assert result.status == StepStatus.COMPLETED
assert "--integration-options" in result.output["argv"]
assert "--skills" in result.output["argv"]
assert result.output["integration_options"] == "--skills"
def test_validate_rejects_bad_script(self):
from specify_cli.workflows.steps.init import InitStep
step = InitStep()
errors = step.validate({"id": "bootstrap", "script": "bogus"})
assert any("'script' must be 'sh' or 'ps'" in e for e in errors)
def test_validate_accepts_valid(self):
from specify_cli.workflows.steps.init import InitStep
step = InitStep()
assert step.validate({"id": "bootstrap", "script": "sh"}) == []
class TestGateStep:
"""Test the gate step type."""

4
workflows/ARCHITECTURE.md
View File

@@ -77,13 +77,14 @@ When a `gate` step pauses execution, the engine persists `current_step_index` an
## Step Types
The engine ships with 10 built-in step types, each in its own subpackage under `src/specify_cli/workflows/steps/`:
The engine ships with 11 built-in step types, each in its own subpackage under `src/specify_cli/workflows/steps/`:
| Type Key | Class | Purpose | Returns `next_steps`? |
|----------|-------|---------|-----------------------|
| `command` | `CommandStep` | Invoke an installed Spec Kit command via integration CLI | No |
| `prompt` | `PromptStep` | Send an arbitrary inline prompt to integration CLI | No |
| `shell` | `ShellStep` | Run a shell command, capture output | No |
| `init` | `InitStep` | Bootstrap a project (equivalent to `specify init`) | No |
| `gate` | `GateStep` | Interactive human review/approval | No (pauses in CI) |
| `if` | `IfThenStep` | Conditional branching (then/else) | Yes |
| `switch` | `SwitchStep` | Multi-branch dispatch on expression | Yes |
@@ -197,6 +198,7 @@ src/specify_cli/
│ └── steps/
│ ├── command/ # Dispatch command to AI integration
│ ├── shell/ # Run shell command
│ ├── init/ # Bootstrap a project (specify init)
│ ├── gate/ # Human review checkpoint
│ ├── if_then/ # Conditional branching
│ ├── prompt/ # Arbitrary inline prompts

20
workflows/README.md
View File

@@ -78,7 +78,7 @@ specify workflow run speckit \
## Step Types
Workflows support 10 built-in step types:
Workflows support 11 built-in step types:
### Command Steps (default)
@@ -114,6 +114,24 @@ Run a shell command and capture output:
run: "cd {{ inputs.project_dir }} && npm test"
```
### Init Steps
Bootstrap a project the same way `specify init` does — scaffolding
templates, scripts, shared infrastructure, and the selected coding agent
integration. Runs non-interactively (defaults to `--ignore-agent-tools`)
and resolves the integration from the step config or the workflow default:
```yaml
- id: bootstrap
type: init
here: true # or: project: my-project
integration: copilot # Optional: defaults to workflow integration
integration_options: "--skills" # Optional: extra options for the integration
script: sh # Optional: sh or ps
force: true # Optional: required when target directory already exists
preset: healthcare-compliance # Optional preset ID
```
### Gate Steps
Pause for human review. The workflow resumes when `specify workflow resume` is called: