duaer-spec 0.1.0

package/.duaer/extensions/git/scripts/python/create_new_feature_branch.py

@@ -0,0 +1,634 @@
+#!/usr/bin/env python3
+"""Git extension: create_new_feature_branch.py
+
+Creates a git feature branch only. The feature directory and spec file are
+created by the core create-new-feature script. Python port of
+``create-new-feature-branch.sh`` / ``create-new-feature-branch.ps1``.
+
+Loads the core Python helpers from the project's installed scripts when
+available, falling back to the minimal git helpers next to this script.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+MAX_BRANCH_LENGTH = 244  # GitHub enforces a 244-byte limit on branch names
+
+USAGE = (
+    "Usage: create_new_feature_branch.py [--json] [--dry-run] "
+    "[--allow-existing-branch] [--short-name <name>] [--number N] "
+    "[--timestamp] <feature_description>"
+)
+
+HELP_TEXT = f"""{USAGE}
+
+Options:
+  --json              Output in JSON format
+  --dry-run           Compute branch name without creating the branch
+  --allow-existing-branch  Switch to branch if it already exists instead of failing
+  --short-name <name> Provide a custom short name (2-4 words) for the branch
+  --number N          Specify branch number manually (overrides auto-detection)
+  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering
+  --help, -h          Show this help message
+
+Environment variables:
+  GIT_BRANCH_NAME     Use this exact branch name, bypassing all prefix/suffix generation
+
+Configuration:
+  branch_template     Optional git-config.yml template with {{author}}, {{app}}, {{number}}, {{slug}}
+  branch_prefix       Optional shorthand namespace expanded before {{number}}-{{slug}}
+
+Examples:
+  create_new_feature_branch.py 'Add user authentication system' --short-name 'user-auth'
+  create_new_feature_branch.py 'Implement OAuth2 integration for API' --number 5
+  create_new_feature_branch.py --timestamp --short-name 'user-auth' 'Add user authentication'
+  GIT_BRANCH_NAME=my-branch create_new_feature_branch.py 'feature description'
+"""
+
+STOP_WORDS = frozenset(
+    "i a an the to for of in on at by with from is are was were be been being "
+    "have has had do does did will would should could can may might must shall "
+    "this that these those my your our their want need add get set".split()
+)
+
+
+def _err(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+def _persist_hint(var_name: str, value: str) -> str:
+    """Shell-appropriate guidance for persisting an env var in the caller's shell."""
+    if os.name == "nt":
+        escaped_value = value.replace("'", "''")
+        return f"$env:{var_name} = '{escaped_value}'"
+    escaped_value = re.sub(r"([^\w@%+=:,./-])", r"\\\1", value)
+    return f"export {var_name}={escaped_value}"
+
+
+@dataclass
+class Args:
+    json_mode: bool = False
+    dry_run: bool = False
+    allow_existing: bool = False
+    short_name: str = ""
+    branch_number: str = ""
+    use_timestamp: bool = False
+    description_parts: list[str] = field(default_factory=list)
+
+
+def parse_args(argv: list[str]) -> Args:
+    args = Args()
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--json":
+            args.json_mode = True
+        elif arg == "--dry-run":
+            args.dry_run = True
+        elif arg == "--allow-existing-branch":
+            args.allow_existing = True
+        elif arg == "--short-name":
+            if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
+                _err("Error: --short-name requires a value")
+                raise SystemExit(1)
+            i += 1
+            args.short_name = argv[i]
+        elif arg == "--number":
+            if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
+                _err("Error: --number requires a value")
+                raise SystemExit(1)
+            i += 1
+            args.branch_number = argv[i]
+            if not re.fullmatch(r"[0-9]+", args.branch_number):
+                _err("Error: --number must be a non-negative integer")
+                raise SystemExit(1)
+        elif arg == "--timestamp":
+            args.use_timestamp = True
+        elif arg in ("--help", "-h"):
+            print(HELP_TEXT)
+            raise SystemExit(0)
+        else:
+            args.description_parts.append(arg)
+        i += 1
+    return args
+
+
+# ── Core helpers loading ─────────────────────────────────────────────────────
+
+
+def _find_project_root(start: Path) -> Path | None:
+    current = start
+    while True:
+        if (current / ".duaer").is_dir() or (current / ".git").exists():
+            return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def _load_core_common(project_root: Path | None):
+    """Load the core common.py from the project's installed scripts.
+
+    Search locations in priority order, mirroring the bash script:
+     1. .duaer/scripts/python/common.py (installed project)
+     2. scripts/python/common.py (source checkout fallback)
+    Returns the loaded module or None.
+    """
+    if project_root is None:
+        return None
+    for relative in (".duaer/scripts/python/common.py", "scripts/python/common.py"):
+        candidate = project_root / relative
+        if candidate.is_file():
+            spec = importlib.util.spec_from_file_location("speckit_core_common", candidate)
+            if spec is None or spec.loader is None:
+                continue
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[spec.name] = module
+            spec.loader.exec_module(module)
+            return module
+    return None
+
+
+def _local_has_git(repo_root: Path) -> bool:
+    git_marker = repo_root / ".git"
+    if not (git_marker.is_dir() or git_marker.is_file()):
+        return False
+    if shutil.which("git") is None:
+        return False
+    return (
+        subprocess.run(
+            ["git", "-C", str(repo_root), "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+        ).returncode
+        == 0
+    )
+
+
+# ── Numbering ────────────────────────────────────────────────────────────────
+
+
+def get_highest_from_specs(specs_dir: Path) -> int:
+    highest = 0
+    if specs_dir.is_dir():
+        for entry in specs_dir.iterdir():
+            if not entry.is_dir():
+                continue
+            name = entry.name
+            # Match sequential prefixes (>=3 digits), but skip timestamp dirs.
+            if re.match(r"^[0-9]{3,}-", name) and not re.match(
+                r"^[0-9]{8}-[0-9]{6}-", name
+            ):
+                number = int(re.match(r"^[0-9]+", name).group(0))
+                highest = max(highest, number)
+    return highest
+
+
+def _extract_highest_number(names: list[str], scope_prefix: str) -> int:
+    """Extract the highest sequential feature number from a list of ref names."""
+    highest = 0
+    for name in names:
+        if not name:
+            continue
+        if scope_prefix:
+            if not name.startswith(scope_prefix):
+                continue
+            name = name[len(scope_prefix) :]
+        name = name.rsplit("/", 1)[-1]
+        if (
+            re.match(r"^[0-9]{3,}-", name)
+            and not re.match(r"^[0-9]{8}-[0-9]{6}-", name)
+            and not re.match(r"^[0-9]{7}-[0-9]{6}-", name)
+            and not re.fullmatch(r"[0-9]{7,8}-[0-9]{6}", name)
+        ):
+            match = re.match(r"^([0-9]{3,})-", name)
+            number = int(match.group(1)) if match else 0
+            highest = max(highest, number)
+    return highest
+
+
+def _git_lines(repo_root: Path, *args: str, env_extra: dict | None = None) -> list[str]:
+    if shutil.which("git") is None:
+        return []
+    env = {**os.environ, **(env_extra or {})}
+    result = subprocess.run(
+        ["git", *args], cwd=repo_root, capture_output=True, text=True, env=env
+    )
+    if result.returncode != 0:
+        return []
+    return result.stdout.splitlines()
+
+
+def get_highest_from_branches(repo_root: Path, scope_prefix: str) -> int:
+    names = []
+    for line in _git_lines(repo_root, "branch", "-a"):
+        line = re.sub(r"^[+*]\s+", "", line)
+        line = line.lstrip()
+        line = re.sub(r"^remotes/[^/]*/", "", line)
+        names.append(line)
+    return _extract_highest_number(names, scope_prefix)
+
+
+def get_highest_from_remote_refs(repo_root: Path, scope_prefix: str) -> int:
+    """Highest number from remote branches without fetching (side-effect-free)."""
+    highest = 0
+    for remote in _git_lines(repo_root, "remote"):
+        refs = _git_lines(
+            repo_root,
+            "ls-remote",
+            "--heads",
+            remote,
+            env_extra={"GIT_TERMINAL_PROMPT": "0"},
+        )
+        names = [re.sub(r".*refs/heads/", "", ref) for ref in refs]
+        highest = max(highest, _extract_highest_number(names, scope_prefix))
+    return highest
+
+
+def check_existing_branches(
+    repo_root: Path, specs_dir: Path, skip_fetch: bool, scope_prefix: str
+) -> int:
+    """Check existing branches and return the next available number."""
+    if skip_fetch:
+        highest_branch = max(
+            get_highest_from_remote_refs(repo_root, scope_prefix),
+            get_highest_from_branches(repo_root, scope_prefix),
+        )
+    else:
+        subprocess.run(
+            ["git", "fetch", "--all", "--prune"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+        )
+        highest_branch = get_highest_from_branches(repo_root, scope_prefix)
+
+    return max(highest_branch, get_highest_from_specs(specs_dir)) + 1
+
+
+# ── Branch naming ────────────────────────────────────────────────────────────
+
+
+def clean_branch_name(name: str) -> str:
+    name = re.sub(r"[^a-z0-9]", "-", name.lower())
+    name = re.sub(r"-+", "-", name)
+    return name.strip("-")
+
+
+def generate_branch_name(description: str) -> str:
+    """Generate a branch suffix from the description with stop word filtering."""
+    clean_name = re.sub(r"[^a-z0-9]", " ", description.lower())
+
+    meaningful_words = []
+    for word in clean_name.split():
+        if word in STOP_WORDS:
+            continue
+        if len(word) >= 3:
+            meaningful_words.append(word)
+        # Keep short words only when they appear uppercased in the original
+        # description (acronyms like "API" or "DB").
+        elif re.search(rf"\b{re.escape(word.upper())}\b", description):
+            meaningful_words.append(word)
+
+    if meaningful_words:
+        max_words = 4 if len(meaningful_words) == 4 else 3
+        return "-".join(meaningful_words[:max_words])
+
+    cleaned = clean_branch_name(description)
+    return "-".join([part for part in cleaned.split("-") if part][:3])
+
+
+def branch_token(value: str, fallback: str) -> str:
+    cleaned = clean_branch_name(value)
+    return cleaned if cleaned else fallback
+
+
+def get_author_token(repo_root: Path) -> str:
+    author = ""
+    if shutil.which("git") is not None:
+        lines = _git_lines(repo_root, "config", "user.name")
+        author = lines[0] if lines else ""
+        if not author:
+            lines = _git_lines(repo_root, "config", "user.email")
+            email = lines[0] if lines else ""
+            author = email.split("@")[0]
+    if not author:
+        author = os.environ.get("USER") or os.environ.get("USERNAME") or "unknown"
+    return branch_token(author, "unknown")
+
+
+def get_app_token(repo_root: Path) -> str:
+    return branch_token(repo_root.name, "app")
+
+
+def read_git_config_value(config_file: Path, key: str) -> str:
+    if not config_file.is_file():
+        return ""
+    try:
+        lines = config_file.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return ""
+    for line in lines:
+        if re.match(rf"^\s*{re.escape(key)}:", line):
+            value = re.sub(rf"^\s*{re.escape(key)}:\s*", "", line)
+            value = re.sub(r"\s+#.*$", "", value)
+            value = value.strip()
+            value = re.sub(r'^"|"$', "", value)
+            value = re.sub(r"^'|'$", "", value)
+            return value
+    return ""
+
+
+def resolve_branch_template(config_file: Path) -> str:
+    template = read_git_config_value(config_file, "branch_template")
+    if template:
+        return template
+
+    prefix = read_git_config_value(config_file, "branch_prefix")
+    if not prefix:
+        return ""
+    if prefix.endswith("/"):
+        return f"{prefix}{{number}}-{{slug}}"
+    return f"{prefix}/{{number}}-{{slug}}"
+
+
+def validate_branch_template(template: str) -> None:
+    if not template:
+        return
+    if "{number}" not in template:
+        _err(
+            "Error: branch_template must include the {number} token so generated "
+            "branches remain valid feature branches."
+        )
+        raise SystemExit(1)
+    slug_index = template.find("{slug}")
+    if slug_index != -1 and "{number}" in template[slug_index:]:
+        _err(
+            "Error: branch_template must not place {slug} before {number}; "
+            "use {slug} only in the final feature segment."
+        )
+        raise SystemExit(1)
+    feature_segment = template.rsplit("/", 1)[-1]
+    if not feature_segment.startswith("{number}-"):
+        _err(
+            "Error: branch_template must put {number}- at the start of the final "
+            "path segment so generated branches remain valid feature branches."
+        )
+        raise SystemExit(1)
+
+
+def render_branch_template(
+    template: str, feature_num: str, branch_suffix: str, author_token: str, app_token: str
+) -> str:
+    rendered = template
+    rendered = rendered.replace("{author}", author_token)
+    rendered = rendered.replace("{app}", app_token)
+    rendered = rendered.replace("{number}", feature_num)
+    rendered = rendered.replace("{slug}", branch_suffix)
+    return rendered
+
+
+def extract_feature_num_from_branch(branch_name: str) -> str:
+    feature_segment = branch_name.rsplit("/", 1)[-1]
+    match = re.match(r"^[0-9]{8}-[0-9]{6}-", feature_segment)
+    if match:
+        return match.group(0).rstrip("-")
+    match = re.match(r"^[0-9]+-", feature_segment)
+    if match:
+        return match.group(0).rstrip("-")
+    return branch_name
+
+
+def _byte_length(value: str) -> int:
+    return len(value.encode("utf-8"))
+
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+
+    feature_description = " ".join(args.description_parts)
+    if not feature_description:
+        _err(USAGE)
+        return 1
+    feature_description = feature_description.strip()
+    if not feature_description:
+        _err("Error: Feature description cannot be empty or contain only whitespace")
+        return 1
+
+    project_root = _find_project_root(SCRIPT_DIR)
+    core = _load_core_common(project_root)
+
+    # SPECIFY_INIT_DIR is resolved (and validated) by the core resolver. If the
+    # core helpers were not found, refuse rather than silently falling back to
+    # the wrong root.
+    if os.environ.get("SPECIFY_INIT_DIR") and (
+        core is None or not hasattr(core, "resolve_specify_init_dir")
+    ):
+        _err(
+            "Error: SPECIFY_INIT_DIR requires updated Duaer core scripts "
+            "(common.py with resolve_specify_init_dir), which were not found."
+        )
+        return 1
+
+    if core is not None and hasattr(core, "get_repo_root"):
+        # Pass script path so cwd-outside-repo callers land on the same
+        # fallback the bash twin does. Older cores don't accept the kwarg —
+        # fall back to the no-arg call for compatibility.
+        try:
+            repo_root = core.get_repo_root(script_file=Path(__file__))
+        except TypeError:
+            repo_root = core.get_repo_root()
+    else:
+        toplevel = _git_lines(Path.cwd(), "rev-parse", "--show-toplevel")
+        if toplevel:
+            repo_root = Path(toplevel[0])
+        elif project_root is not None:
+            repo_root = project_root
+        else:
+            _err("Error: Could not determine repository root.")
+            return 1
+    repo_root = Path(repo_root)
+
+    has_git_repo = _local_has_git(repo_root)
+
+    specs_dir = repo_root / "specs"
+    config_file = repo_root / ".duaer" / "extensions" / "git" / "git-config.yml"
+
+    author_token = get_author_token(repo_root)
+    app_token = get_app_token(repo_root)
+    branch_template = resolve_branch_template(config_file)
+    validate_branch_template(branch_template)
+
+    def build_branch_name(feature_num: str, branch_suffix: str) -> str:
+        if branch_template:
+            return render_branch_template(
+                branch_template, feature_num, branch_suffix, author_token, app_token
+            )
+        return f"{feature_num}-{branch_suffix}"
+
+    branch_number = args.branch_number
+
+    # Check for GIT_BRANCH_NAME env var override (exact name, no prefix/suffix)
+    env_branch_name = os.environ.get("GIT_BRANCH_NAME", "")
+    if env_branch_name:
+        branch_name = env_branch_name
+        feature_num = extract_feature_num_from_branch(branch_name)
+        branch_suffix = branch_name
+    else:
+        if args.short_name:
+            branch_suffix = clean_branch_name(args.short_name)
+        else:
+            branch_suffix = generate_branch_name(feature_description)
+
+        if args.use_timestamp and branch_number:
+            _err("[specify] Warning: --number is ignored when --timestamp is used")
+            branch_number = ""
+
+        if args.use_timestamp:
+            feature_num = datetime.now().strftime("%Y%m%d-%H%M%S")
+            branch_name = build_branch_name(feature_num, branch_suffix)
+        else:
+            scope_prefix = ""
+            if branch_template:
+                prefix_template = branch_template.split("{number}")[0]
+                scope_prefix = render_branch_template(
+                    prefix_template, "", branch_suffix, author_token, app_token
+                )
+            if not branch_number:
+                if args.dry_run and has_git_repo:
+                    branch_number = check_existing_branches(
+                        repo_root, specs_dir, True, scope_prefix
+                    )
+                elif args.dry_run:
+                    branch_number = get_highest_from_specs(specs_dir) + 1
+                elif has_git_repo:
+                    branch_number = check_existing_branches(
+                        repo_root, specs_dir, False, scope_prefix
+                    )
+                else:
+                    branch_number = get_highest_from_specs(specs_dir) + 1
+
+            feature_num = f"{int(branch_number):03d}"
+            branch_name = build_branch_name(feature_num, branch_suffix)
+
+    branch_byte_len = _byte_length(branch_name)
+    if env_branch_name and branch_byte_len > MAX_BRANCH_LENGTH:
+        _err(
+            "Error: GIT_BRANCH_NAME must be 244 bytes or fewer in UTF-8. "
+            f"Provided value is {branch_byte_len} bytes."
+        )
+        return 1
+    if branch_byte_len > MAX_BRANCH_LENGTH:
+        original_branch_name = branch_name
+        truncated_suffix = branch_suffix
+        while _byte_length(branch_name) > MAX_BRANCH_LENGTH and truncated_suffix:
+            truncated_suffix = truncated_suffix[:-1]
+            truncated_suffix = truncated_suffix.rstrip("-")
+            branch_name = build_branch_name(feature_num, truncated_suffix)
+        if _byte_length(branch_name) > MAX_BRANCH_LENGTH:
+            _err("Error: Branch template prefix exceeds GitHub's 244-byte branch name limit.")
+            return 1
+
+        _err("[specify] Warning: Branch name exceeded GitHub's 244-byte limit")
+        _err(
+            f"[specify] Original: {original_branch_name} "
+            f"({_byte_length(original_branch_name)} bytes)"
+        )
+        _err(f"[specify] Truncated to: {branch_name} ({_byte_length(branch_name)} bytes)")
+
+    if not args.dry_run:
+        if has_git_repo:
+            create = subprocess.run(
+                ["git", "checkout", "-q", "-b", branch_name],
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+            )
+            if create.returncode != 0:
+                current_branch_lines = _git_lines(
+                    repo_root, "rev-parse", "--abbrev-ref", "HEAD"
+                )
+                current_branch = current_branch_lines[0] if current_branch_lines else ""
+                branch_exists = bool(
+                    _git_lines(repo_root, "branch", "--list", branch_name)
+                )
+                if branch_exists:
+                    if args.allow_existing:
+                        if current_branch != branch_name:
+                            switch = subprocess.run(
+                                ["git", "checkout", "-q", branch_name],
+                                cwd=repo_root,
+                                capture_output=True,
+                                text=True,
+                            )
+                            if switch.returncode != 0:
+                                _err(
+                                    f"Error: Failed to switch to existing branch '{branch_name}'. "
+                                    "Please resolve any local changes or conflicts and try again."
+                                )
+                                if switch.stderr.strip():
+                                    _err(switch.stderr.strip())
+                                return 1
+                    elif args.use_timestamp:
+                        _err(
+                            f"Error: Branch '{branch_name}' already exists. Rerun to get "
+                            "a new timestamp or use a different --short-name."
+                        )
+                        return 1
+                    else:
+                        _err(
+                            f"Error: Branch '{branch_name}' already exists. Please use a "
+                            "different feature name or specify a different number with --number."
+                        )
+                        return 1
+                else:
+                    _err(f"Error: Failed to create git branch '{branch_name}'.")
+                    if create.stderr.strip():
+                        _err(create.stderr.strip())
+                    else:
+                        _err("Please check your git configuration and try again.")
+                    return 1
+        else:
+            _err(
+                "[specify] Warning: Git repository not detected; skipped branch "
+                f"creation for {branch_name}"
+            )
+
+        _err(f"# To persist: {_persist_hint('SPECIFY_FEATURE', branch_name)}")
+
+    if args.json_mode:
+        payload: dict[str, object] = {
+            "BRANCH_NAME": branch_name,
+            "FEATURE_NUM": feature_num,
+        }
+        if args.dry_run:
+            payload["DRY_RUN"] = True
+        print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
+    else:
+        print(f"BRANCH_NAME: {branch_name}")
+        print(f"FEATURE_NUM: {feature_num}")
+        if not args.dry_run:
+            print(
+                "# To persist in your shell: "
+                f"{_persist_hint('SPECIFY_FEATURE', branch_name)}"
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))