💫 Toolkit to help you get started with SDD or any other process!
fix(plan): use .specify/feature.json to allow /speckit.plan on custom git branches (#2305) (#2349)
Adrian Osorio Blanchard37745ec2ee2c
diff --git a/scripts/bash/common.sh b/scripts/bash/common.shindex cad10bdb3..03141e446 100644--- a/scripts/bash/common.sh+++ b/scripts/bash/common.sh@@ -153,6 +153,59 @@ check_feature_branch() {return 0}+# Safely read .specify/feature.json's "feature_directory" value.+# Prints the raw value (possibly relative) to stdout, or empty string if the file+# is missing, unparseable, or does not contain the key. Always returns 0 so callers+# under `set -e` cannot be aborted by parser failure.+# Parser order mirrors the historical get_feature_paths behavior: jq -> python3 -> grep/sed.+read_feature_json_feature_directory() {+ local repo_root="$1"+ local fj="$repo_root/.specify/feature.json"+ [[ -f "$fj" ]] || { printf '%s' ''; return 0; }++ local _fd=''+ if command -v jq >/dev/null 2>&1; then+ if ! _fd=$(jq -r '.feature_directory // empty' "$fj" 2>/dev/null); then+ _fd=''+ fi+ elif command -v python3 >/dev/null 2>&1; then+ # Use Python so pretty-printed/multi-line JSON still parses correctly.+ if ! _fd=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); v=d.get('feature_directory'); print(v if v else '')" "$fj" 2>/dev/null); then+ _fd=''+ fi+ else+ # Last-resort single-line grep/sed fallback. The `|| true` guards against+ # grep returning 1 (no match) aborting under `set -e` / `pipefail`.+ _fd=$( { grep -E '"feature_directory"[[:space:]]*:' "$fj" 2>/dev/null || true; } \+ | head -n 1 \+ | sed -E 's/^[^:]*:[[:space:]]*"([^"]*)".*$/\1/' )+ fi++ printf '%s' "$_fd"+ return 0+}++# Returns 0 when .specify/feature.json lists feature_directory that exists as a directory+# and matches the resolved active FEATURE_DIR (so /speckit.plan can skip git branch pattern checks).+# Delegates parsing to read_feature_json_feature_directory, which is safe under `set -e`.+feature_json_matches_feature_dir() {+ local repo_root="$1"+ local active_feature_dir="$2"++ local _fd+ _fd=$(read_feature_json_feature_directory "$repo_root")++ [[ -n "$_fd" ]] || return 1+ [[ "$_fd" != /* ]] && _fd="$repo_root/$_fd"+ [[ -d "$_fd" ]] || return 1++ local norm_json norm_active+ norm_json="$(cd -- "$_fd" 2>/dev/null && pwd -P)" || return 1+ norm_active="$(cd -- "$active_feature_dir" 2>/dev/null && pwd -P)" || return 1++ [[ "$norm_json" == "$norm_active" ]]+}+# Find feature directory by numeric prefix instead of exact branch match# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)find_feature_dir_by_prefix() {@@ -217,16 +270,10 @@ get_feature_paths() {# Normalize relative paths to absolute under repo root[[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"elif [[ -f "$repo_root/.specify/feature.json" ]]; then+ # Shared, set -e-safe parser: jq -> python3 -> grep/sed. Returns empty on+ # missing/unparseable/unset so we fall through to the branch-prefix lookup.local _fd- if command -v jq >/dev/null 2>&1; then- _fd=$(jq -r '.feature_directory // empty' "$repo_root/.specify/feature.json" 2>/dev/null)- elif command -v python3 >/dev/null 2>&1; then- # Fallback: use Python to parse JSON so pretty-printed/multi-line files work- _fd=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('feature_directory',''))" "$repo_root/.specify/feature.json" 2>/dev/null)- else- # Last resort: single-line grep fallback (won't work on multi-line JSON)- _fd=$(grep -o '"feature_directory"[[:space:]]*:[[:space:]]*"[^"]*"' "$repo_root/.specify/feature.json" 2>/dev/null | sed 's/.*"\([^"]*\)"$/\1/')- fi+ _fd=$(read_feature_json_feature_directory "$repo_root")if [[ -n "$_fd" ]]; thenfeature_dir="$_fd"# Normalize relative paths to absolute under repo rootdiff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.shindex 9f5523149..f2d2f6e6f 100644--- a/scripts/bash/setup-plan.sh+++ b/scripts/bash/setup-plan.sh@@ -32,8 +32,10 @@ _paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature peval "$_paths_output"unset _paths_output-# Check if we're on a proper feature branch (only for git repos)-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1+# If feature.json pins an existing feature directory, branch naming is not required.+if ! feature_json_matches_feature_dir "$REPO_ROOT" "$FEATURE_DIR"; then+ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1+fi# Ensure the feature directory existsmkdir -p "$FEATURE_DIR"diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1index d799e4f7e..ffc6d73b3 100644--- a/scripts/powershell/common.ps1+++ b/scripts/powershell/common.ps1@@ -164,6 +164,74 @@ function Test-FeatureBranch {return $true}+# True when .specify/feature.json pins an existing feature directory that matches the+# active FEATURE_DIR from Get-FeaturePathsEnv (so /speckit.plan can skip git branch pattern checks).+function Test-FeatureJsonMatchesFeatureDir {+ param(+ [Parameter(Mandatory = $true)][string]$RepoRoot,+ [Parameter(Mandatory = $true)][string]$ActiveFeatureDir+ )++ $featureJson = Join-Path (Join-Path $RepoRoot '.specify') 'feature.json'+ if (-not (Test-Path -LiteralPath $featureJson -PathType Leaf)) {+ return $false+ }++ try {+ $raw = Get-Content -LiteralPath $featureJson -Raw+ $cfg = $raw | ConvertFrom-Json+ } catch {+ return $false+ }++ $fd = $cfg.feature_directory+ if ([string]::IsNullOrWhiteSpace([string]$fd)) {+ return $false+ }++ if (-not [System.IO.Path]::IsPathRooted($fd)) {+ $fd = Join-Path $RepoRoot $fd+ }++ if (-not (Test-Path -LiteralPath $fd -PathType Container)) {+ return $false+ }++ # Resolve both paths to canonical absolute form. Prefer Resolve-Path (follows+ # symlinks and is the canonical PS way); fall back to [Path]::GetFullPath when+ # Resolve-Path can't produce a value. Mirrors the pattern used by Find-SpecifyRoot.+ $resolvedJson = Resolve-Path -LiteralPath $fd -ErrorAction SilentlyContinue+ if ($resolvedJson) {+ $normJson = $resolvedJson.Path+ } else {+ $normJson = [System.IO.Path]::GetFullPath($fd)+ }++ $resolvedActive = Resolve-Path -LiteralPath $ActiveFeatureDir -ErrorAction SilentlyContinue+ if ($resolvedActive) {+ $normActive = $resolvedActive.Path+ } else {+ $normActive = [System.IO.Path]::GetFullPath($ActiveFeatureDir)+ }++ # Use case-insensitive compare only on Windows; POSIX filesystems are case-sensitive.+ # PowerShell 5.1 is Windows-only and does not define $IsWindows, so treat its+ # absence as "we're on Windows".+ if ($null -ne $IsWindows) {+ $onWindows = $IsWindows+ } else {+ $onWindows = $true+ }++ if ($onWindows) {+ $comparison = [System.StringComparison]::OrdinalIgnoreCase+ } else {+ $comparison = [System.StringComparison]::Ordinal+ }++ return [string]::Equals($normJson, $normActive, $comparison)+}+# Resolve specs/<feature-dir> by numeric/timestamp prefix (mirrors scripts/bash/common.sh find_feature_dir_by_prefix).function Find-FeatureDirByPrefix {param(diff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1index ee09094bf..15ae55754 100644--- a/scripts/powershell/setup-plan.ps1+++ b/scripts/powershell/setup-plan.ps1@@ -23,9 +23,11 @@ if ($Help) {# Get all paths and variables from common functions$paths = Get-FeaturePathsEnv-# Check if we're on a proper feature branch (only for git repos)-if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GIT)) {- exit 1+# If feature.json pins an existing feature directory, branch naming is not required.+if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFeatureDir $paths.FEATURE_DIR)) {+ if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GIT)) {+ exit 1+ }}# Ensure the feature directory existsdiff --git a/tests/test_setup_plan_feature_json.py b/tests/test_setup_plan_feature_json.pynew file mode 100644index 000000000..0203b3670--- /dev/null+++ b/tests/test_setup_plan_feature_json.py@@ -0,0 +1,202 @@+"""Tests for setup-plan bypassing branch-pattern checks when feature.json is valid."""++import json+import os+import shutil+import subprocess+from pathlib import Path++import pytest++from tests.conftest import requires_bash++PROJECT_ROOT = Path(__file__).resolve().parent.parent+COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"+SETUP_PLAN_SH = PROJECT_ROOT / "scripts" / "bash" / "setup-plan.sh"+COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"+SETUP_PLAN_PS = PROJECT_ROOT / "scripts" / "powershell" / "setup-plan.ps1"+PLAN_TEMPLATE = PROJECT_ROOT / "templates" / "plan-template.md"++HAS_PWSH = shutil.which("pwsh") is not None+_POWERSHELL = shutil.which("powershell.exe") or shutil.which("powershell")+++def _install_bash_scripts(repo: Path) -> None:+ d = repo / ".specify" / "scripts" / "bash"+ d.mkdir(parents=True, exist_ok=True)+ shutil.copy(COMMON_SH, d / "common.sh")+ shutil.copy(SETUP_PLAN_SH, d / "setup-plan.sh")+++def _install_ps_scripts(repo: Path) -> None:+ d = repo / ".specify" / "scripts" / "powershell"+ d.mkdir(parents=True, exist_ok=True)+ shutil.copy(COMMON_PS, d / "common.ps1")+ shutil.copy(SETUP_PLAN_PS, d / "setup-plan.ps1")+++def _minimal_templates(repo: Path) -> None:+ tdir = repo / ".specify" / "templates"+ tdir.mkdir(parents=True, exist_ok=True)+ shutil.copy(PLAN_TEMPLATE, tdir / "plan-template.md")+++def _clean_env() -> dict[str, str]:+ """Return a copy of the current environment with any SPECIFY_* vars removed.++ setup-plan.{sh,ps1} honors SPECIFY_FEATURE, SPECIFY_FEATURE_DIRECTORY, etc.,+ which would otherwise leak from a developer shell or CI runner and make these+ tests flaky. Stripping them forces every case to rely purely on git branch ++ .specify/feature.json state set up by the fixture.+ """+ env = os.environ.copy()+ for key in list(env):+ if key.startswith("SPECIFY_"):+ env.pop(key)+ return env+++def _git_init(repo: Path) -> None:+ subprocess.run(["git", "init", "-q"], cwd=repo, check=True)+ subprocess.run(+ ["git", "config", "user.email", "[email protected]"], cwd=repo, check=True+ )+ subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)+ subprocess.run(+ ["git", "commit", "--allow-empty", "-m", "init", "-q"], cwd=repo, check=True+ )+++def plan_repo(tmp_path: Path) -> Path:+ repo = tmp_path / "proj"+ repo.mkdir()+ _git_init(repo)+ (repo / ".specify").mkdir()+ _minimal_templates(repo)+ _install_bash_scripts(repo)+ _install_ps_scripts(repo)+ return repo+++@requires_bash+def test_setup_plan_passes_custom_branch_when_feature_json_valid(plan_repo: Path) -> None:+ subprocess.run(+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],+ cwd=plan_repo,+ check=True,+ )+ feat = plan_repo / "specs" / "001-tiny-notes-app"+ feat.mkdir(parents=True)+ (feat / "spec.md").write_text("# spec\n", encoding="utf-8")+ (plan_repo / ".specify" / "feature.json").write_text(+ json.dumps({"feature_directory": "specs/001-tiny-notes-app"}),+ encoding="utf-8",+ )+ script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"+ result = subprocess.run(+ ["bash", str(script)],+ cwd=plan_repo,+ capture_output=True,+ text=True,+ check=False,+ env=_clean_env(),+ )+ assert result.returncode == 0, result.stderr + result.stdout+ assert (feat / "plan.md").is_file()+++@requires_bash+def test_setup_plan_fails_custom_branch_without_feature_json(plan_repo: Path) -> None:+ subprocess.run(+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],+ cwd=plan_repo,+ check=True,+ )+ script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"+ result = subprocess.run(+ ["bash", str(script)],+ cwd=plan_repo,+ capture_output=True,+ text=True,+ check=False,+ env=_clean_env(),+ )+ assert result.returncode != 0+ assert "Not on a feature branch" in result.stderr+++@requires_bash+def test_setup_plan_numbered_branch_unchanged_without_feature_json(+ plan_repo: Path,+) -> None:+ subprocess.run(+ ["git", "checkout", "-q", "-b", "001-tiny-notes-app"],+ cwd=plan_repo,+ check=True,+ )+ feat = plan_repo / "specs" / "001-tiny-notes-app"+ feat.mkdir(parents=True)+ (feat / "spec.md").write_text("# spec\n", encoding="utf-8")+ script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"+ result = subprocess.run(+ ["bash", str(script)],+ cwd=plan_repo,+ capture_output=True,+ text=True,+ check=False,+ env=_clean_env(),+ )+ assert result.returncode == 0, result.stderr + result.stdout+ assert (feat / "plan.md").is_file()++[email protected](not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")+def test_setup_plan_ps_passes_custom_branch_when_feature_json_valid(plan_repo: Path) -> None:+ subprocess.run(+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],+ cwd=plan_repo,+ check=True,+ )+ feat = plan_repo / "specs" / "001-tiny-notes-app"+ feat.mkdir(parents=True)+ (feat / "spec.md").write_text("# spec\n", encoding="utf-8")+ (plan_repo / ".specify" / "feature.json").write_text(+ json.dumps({"feature_directory": "specs/001-tiny-notes-app"}),+ encoding="utf-8",+ )+ script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"+ exe = "pwsh" if HAS_PWSH else _POWERSHELL+ result = subprocess.run(+ [exe, "-NoProfile", "-File", str(script)],+ cwd=plan_repo,+ capture_output=True,+ text=True,+ check=False,+ env=_clean_env(),+ )+ assert result.returncode == 0, result.stderr + result.stdout+ assert (feat / "plan.md").is_file()++[email protected](not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")+def test_setup_plan_ps_fails_custom_branch_without_feature_json(+ plan_repo: Path,+) -> None:+ subprocess.run(+ ["git", "checkout", "-q", "-b", "feature/my-feature-branch"],+ cwd=plan_repo,+ check=True,+ )+ script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"+ exe = "pwsh" if HAS_PWSH else _POWERSHELL+ result = subprocess.run(+ [exe, "-NoProfile", "-File", str(script)],+ cwd=plan_repo,+ capture_output=True,+ text=True,+ check=False,+ env=_clean_env(),+ )+ assert result.returncode != 0+ assert "Not on a feature branch" in result.stderr