Eliteforge Feature Oriented Release Flow

interface:
  display_name: "eliteforge-feature-oriented-release-flow"
  short_description: "Drive EliteForge release states safely."
  default_prompt: "Use $eliteforge-feature-oriented-release-flow to advance the current version release workflow."

#!/usr/bin/env python3

import argparse
import json
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path


def run_git(args):
    try:
        result = subprocess.run(
            ["git", *args],
            check=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.DEVNULL,
            text=True,
        )
        return result.stdout.strip()
    except subprocess.CalledProcessError:
        return ""


def git_success(args):
    return (
        subprocess.run(
            ["git", *args],
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            text=True,
        ).returncode
        == 0
    )


def require_git_repo():
    if run_git(["rev-parse", "--is-inside-work-tree"]) != "true":
        print("ERROR: current directory is not inside a Git work tree.", file=sys.stderr)
        sys.exit(1)


def default_branch():
    remote_head = run_git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"])
    if remote_head.startswith("origin/"):
        return remote_head.removeprefix("origin/")
    if git_success(["show-ref", "--verify", "--quiet", "refs/remotes/origin/master"]):
        return "master"
    if git_success(["show-ref", "--verify", "--quiet", "refs/remotes/origin/main"]):
        return "main"
    return "master"


def validate_path_segment(name, value):
    if not value:
        print(f"ERROR: {name} must not be empty.", file=sys.stderr)
        sys.exit(2)
    if "/" in value or "\x00" in value:
        print(f"ERROR: {name} must be one filename segment and must not contain '/'.", file=sys.stderr)
        sys.exit(2)


def main():
    parser = argparse.ArgumentParser(
        description="Persist EliteForge feature-oriented release workflow state JSON."
    )
    parser.add_argument("--version", required=True)
    parser.add_argument("--developer", required=True)
    parser.add_argument("--task-id", default="")
    parser.add_argument("--task-name", required=True)
    parser.add_argument(
        "--multi-agent",
        action="store_true",
        help="Persist featureBranch as feature/<version>/<developer>[/<taskId>]/<taskName>/base.",
    )
    parser.add_argument("--state", required=True)
    parser.add_argument("--previous-state", default="")
    parser.add_argument("--notes", default="")
    args = parser.parse_args()

    require_git_repo()

    for name, value in (
        ("version", args.version),
        ("task-name", args.task_name),
    ):
        validate_path_segment(name, value)
    if args.task_id:
        validate_path_segment("task-id", args.task_id)

    if args.task_id:
        task_branch_path = f"{args.version}/{args.developer}/{args.task_id}/{args.task_name}"
        state_filename = f"{args.task_id}-{args.task_name}.json"
        task_id_value = args.task_id
    else:
        task_branch_path = f"{args.version}/{args.developer}/{args.task_name}"
        state_filename = f"{args.task_name}.json"
        task_id_value = None
    non_multi_agent_branch = f"feature/{task_branch_path}"
    multi_agent_base_branch = f"{non_multi_agent_branch}/base"
    branch_mode = "multi_agent" if args.multi_agent else "non_multi_agent"
    feature_branch = multi_agent_base_branch if args.multi_agent else non_multi_agent_branch
    qa_branch = f"qa/{args.version}"
    release_branch = f"release/{args.version}"
    snapshot_version = f"{args.version}-SNAPSHOT"
    state_file = Path("docs/tasks/release-flow") / args.version / state_filename

    now = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
    git_info = {
        "defaultBranch": default_branch(),
        "currentBranch": run_git(["rev-parse", "--abbrev-ref", "HEAD"]) or "HEAD",
        "head": run_git(["rev-parse", "HEAD"]),
        "dirty": bool(run_git(["status", "--porcelain", "--untracked-files=all"])),
    }

    if state_file.exists():
        try:
            data = json.loads(state_file.read_text(encoding="utf-8"))
        except json.JSONDecodeError as exc:
            print(f"ERROR: existing state file is not valid JSON: {state_file}: {exc}", file=sys.stderr)
            sys.exit(1)
        if not isinstance(data, dict):
            print(f"ERROR: existing state file must contain a JSON object: {state_file}", file=sys.stderr)
            sys.exit(1)
    else:
        data = {}

    history = data.get("history", [])
    if not isinstance(history, list):
        history = []

    data.pop("task" + "Desc", None)

    history.append(
        {
            "state": args.state,
            "previousState": args.previous_state,
            "updatedAt": now,
            "head": git_info["head"],
            "currentBranch": git_info["currentBranch"],
            "notes": args.notes,
        }
    )

    data.update(
        {
            "version": args.version,
            "developer": args.developer,
            "taskId": task_id_value,
            "taskName": args.task_name,
            "branchMode": branch_mode,
            "featureBranch": feature_branch,
            "nonMultiAgentBranch": non_multi_agent_branch,
            "multiAgentBaseBranch": multi_agent_base_branch,
            "qaBranch": qa_branch,
            "releaseBranch": release_branch,
            "snapshotVersion": snapshot_version,
            "state": args.state,
            "stateFile": state_file.as_posix(),
            "updatedAt": now,
            "git": git_info,
            "history": history,
        }
    )

    state_file.parent.mkdir(parents=True, exist_ok=True)
    state_file.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
    print(state_file.as_posix())


if __name__ == "__main__":
    main()

#!/usr/bin/env bash

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  release_flow_state.sh --version <version> --developer <developer> [--task-id <taskId>] --task-name <taskName> [--multi-agent] [--check-remote-tags]

Read-only diagnostic helper for the EliteForge feature-oriented release flow.
Run it from the target Git repository before executing a release state transition.

Options:
  --version      Release version, for example 1.0.0
  --developer    Developer segment in the feature branch
  --task-id      Optional task id segment, for example #123
  --task-name    Branch-safe task name segment, for example demo
  --multi-agent  Use feature/<version>/<developer>[/<taskId>]/<taskName>/base
                 as the release-flow feature branch
  --check-remote-tags
                 Also query origin for the version tag. Disabled by default to
                 keep frequent state checks fast and offline-friendly.
  -h, --help     Show this help
EOF
}

version=""
developer=""
task_id=""
task_name=""
check_remote_tags="false"
multi_agent="false"

while [ "$#" -gt 0 ]; do
  case "$1" in
    --version)
      version="${2:-}"
      shift 2
      ;;
    --developer)
      developer="${2:-}"
      shift 2
      ;;
    --task-id)
      task_id="${2:-}"
      shift 2
      ;;
    --task-name)
      task_name="${2:-}"
      shift 2
      ;;
    --check-remote-tags)
      check_remote_tags="true"
      shift
      ;;
    --multi-agent)
      multi_agent="true"
      shift
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      echo "ERROR: unknown argument: $1" >&2
      usage >&2
      exit 2
      ;;
  esac
done

if [ -z "$version" ] || [ -z "$developer" ] || [ -z "$task_name" ]; then
  echo "ERROR: --version, --developer, and --task-name are required." >&2
  usage >&2
  exit 2
fi

if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "ERROR: current directory is not inside a Git work tree." >&2
  exit 1
fi

if [ -n "$task_id" ]; then
  task_branch_path="${version}/${developer}/${task_id}/${task_name}"
  state_file="docs/tasks/release-flow/${version}/${task_id}-${task_name}.json"
else
  task_branch_path="${version}/${developer}/${task_name}"
  state_file="docs/tasks/release-flow/${version}/${task_name}.json"
fi
non_multi_agent_branch="feature/${task_branch_path}"
multi_agent_base_branch="${non_multi_agent_branch}/base"
if [ "$multi_agent" = "true" ]; then
  branch_mode="multi_agent"
  feature_branch="$multi_agent_base_branch"
else
  branch_mode="non_multi_agent"
  feature_branch="$non_multi_agent_branch"
fi
qa_branch="qa/${version}"
release_branch="release/${version}"
snapshot_version="${version}-SNAPSHOT"

default_branch="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || true)"
if [ -z "$default_branch" ]; then
  if git show-ref --verify --quiet refs/remotes/origin/master; then
    default_branch="master"
  elif git show-ref --verify --quiet refs/remotes/origin/main; then
    default_branch="main"
  else
    default_branch="master"
  fi
fi

current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo HEAD)"
dirty="false"
dirty_non_state="false"
status_output="$(git status --porcelain --untracked-files=all)"
if [ -n "$status_output" ]; then
  dirty="true"
  while IFS= read -r status_line; do
    [ -z "$status_line" ] && continue
    status_path="${status_line:3}"
    if [ "$status_path" != "$state_file" ]; then
      dirty_non_state="true"
      break
    fi
  done <<< "$status_output"
fi

exists_local() {
  git show-ref --verify --quiet "refs/heads/$1"
}

exists_remote() {
  git show-ref --verify --quiet "refs/remotes/origin/$1"
}

ahead_count() {
  local base="$1"
  local head="$2"
  if git rev-parse --verify "$base" >/dev/null 2>&1 && git rev-parse --verify "$head" >/dev/null 2>&1; then
    git rev-list --count "${base}..${head}"
  else
    echo "unknown"
  fi
}

upstream_of() {
  local branch="$1"
  git rev-parse --abbrev-ref "${branch}@{upstream}" 2>/dev/null || echo "none"
}

yaml_quote() {
  printf "'"
  printf "%s" "$1" | sed "s/'/''/g"
  printf "'"
}

branch_format_error=""
for candidate_branch in "$feature_branch" "$qa_branch" "$release_branch"; do
  if ! git check-ref-format --branch "$candidate_branch" >/dev/null 2>&1; then
    branch_format_error="$candidate_branch"
    break
  fi
done

state_path_error=""
if [[ "$version" == */* ]]; then
  state_path_error="version contains /"
elif [ -n "$task_id" ] && [[ "$task_id" == */* ]]; then
  state_path_error="task-id contains /"
elif [[ "$task_name" == */* ]]; then
  state_path_error="task-name contains /"
fi

state_hint="BLOCKED"
block_reason=""

if [ "$current_branch" = "HEAD" ]; then
  block_reason="detached HEAD"
elif [ -n "$branch_format_error" ]; then
  block_reason="invalid branch name: $branch_format_error"
elif [ -n "$state_path_error" ]; then
  block_reason="invalid state file segment: $state_path_error"
elif [ "$dirty_non_state" = "true" ]; then
  block_reason="dirty non-state-file paths"
elif ! exists_remote "$default_branch"; then
  block_reason="missing origin/${default_branch}"
elif [ "$multi_agent" = "true" ] && [ "$current_branch" = "$non_multi_agent_branch" ]; then
  block_reason="multi-agent release flow requires the /base branch; rename the non multi-agent branch first"
elif [ "$current_branch" = "$feature_branch" ]; then
  commits="$(ahead_count "origin/${default_branch}" "$feature_branch")"
  if [ "$commits" = "0" ]; then
    state_hint="FEATURE_DEV"
  else
    state_hint="FEATURE_DEV_OR_READY_TO_PUBLISH"
  fi
elif [ "$current_branch" = "nightly" ]; then
  state_hint="DEV_PUBLISH"
elif [ "$current_branch" = "$qa_branch" ]; then
  state_hint="QA_DEPLOY"
elif [ "$current_branch" = "$release_branch" ]; then
  state_hint="RELEASE_MERGE_OR_RELEASE_DEPLOY"
elif [ "$current_branch" = "$default_branch" ]; then
  state_hint="READY_OR_MASTER_BACKMERGE"
else
  state_hint="UNKNOWN_BRANCH"
fi

local_tag="false"
remote_tag="false"
if git show-ref --tags --verify --quiet "refs/tags/$version"; then
  local_tag="true"
fi
if [ "$check_remote_tags" = "true" ]; then
  if git ls-remote --exit-code --tags origin "refs/tags/$version" >/dev/null 2>&1; then
    remote_tag="true"
  fi
else
  remote_tag="not_checked"
fi

cat <<EOF
release_flow_state:
  version: $(yaml_quote "$version")
  developer: $(yaml_quote "$developer")
  task_id: $(yaml_quote "$task_id")
  task_name: $(yaml_quote "$task_name")
  branch_mode: $(yaml_quote "$branch_mode")
  default_branch: $(yaml_quote "$default_branch")
  current_branch: $(yaml_quote "$current_branch")
  dirty: $dirty
  dirty_non_state: $dirty_non_state
  state_hint: $(yaml_quote "$state_hint")
  block_reason: $(yaml_quote "${block_reason:-none}")
branches:
  feature: $(yaml_quote "$feature_branch")
  non_multi_agent: $(yaml_quote "$non_multi_agent_branch")
  multi_agent_base: $(yaml_quote "$multi_agent_base_branch")
  qa: $(yaml_quote "$qa_branch")
  release: $(yaml_quote "$release_branch")
  snapshot_version: $(yaml_quote "$snapshot_version")
  state_file: $(yaml_quote "$state_file")
existence:
  origin_default: $(exists_remote "$default_branch" && echo true || echo false)
  branch_names_valid: $([ -z "$branch_format_error" ] && echo true || echo false)
  state_file_segment_valid: $([ -z "$state_path_error" ] && echo true || echo false)
  local_feature: $(exists_local "$feature_branch" && echo true || echo false)
  remote_feature: $(exists_remote "$feature_branch" && echo true || echo false)
  local_non_multi_agent: $(exists_local "$non_multi_agent_branch" && echo true || echo false)
  remote_non_multi_agent: $(exists_remote "$non_multi_agent_branch" && echo true || echo false)
  local_multi_agent_base: $(exists_local "$multi_agent_base_branch" && echo true || echo false)
  remote_multi_agent_base: $(exists_remote "$multi_agent_base_branch" && echo true || echo false)
  local_qa: $(exists_local "$qa_branch" && echo true || echo false)
  remote_qa: $(exists_remote "$qa_branch" && echo true || echo false)
  local_release: $(exists_local "$release_branch" && echo true || echo false)
  remote_release: $(exists_remote "$release_branch" && echo true || echo false)
upstreams:
  feature: $(yaml_quote "$(exists_local "$feature_branch" && upstream_of "$feature_branch" || echo "missing")")
  qa: $(yaml_quote "$(exists_local "$qa_branch" && upstream_of "$qa_branch" || echo "missing")")
  release: $(yaml_quote "$(exists_local "$release_branch" && upstream_of "$release_branch" || echo "missing")")
tags:
  local_version_tag: $local_tag
  remote_version_tag: $(yaml_quote "$remote_tag")
counts:
  feature_commits_after_origin_default: $(yaml_quote "$(ahead_count "origin/${default_branch}" "$feature_branch")")
EOF