git-acta 1.0.0__py3-none-any.whl

acta/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("git-acta")

acta/cli/__init__.py

@@ -0,0 +1,34 @@
+import click
+
+from acta.cli.board import board
+from acta.cli.branch import branch
+from acta.cli.commit import commit
+from acta.cli.issue import issue
+from acta.cli.milestone import milestone
+from acta.cli.pr import pr, ship, watch
+from acta.cli.release import release
+from acta.cli.shared import CLIGroup
+
+
+@click.group(cls=CLIGroup, invoke_without_command=True)
+@click.version_option(package_name="git-acta")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """Structured git workflow: conventional commits, trunk-based branches, GitHub PR lifecycle.
+
+    Branch names follow the type/scope convention from the conventional commits specification.
+    See https://www.conventionalcommits.org for the full spec.
+    """
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+main.add_command(board)
+main.add_command(branch)
+main.add_command(commit)
+main.add_command(pr)
+main.add_command(ship)
+main.add_command(watch)
+main.add_command(release)
+main.add_command(milestone)
+main.add_command(issue)

acta/cli/board.py

@@ -0,0 +1,56 @@
+import click
+
+from acta.cli.issue import format_issue_lines
+from acta.cli.milestone import format_milestone_line
+from acta.git.branch import get_current_branch
+from acta.git.config import get_active_issue
+from acta.github.issue import issue_list, issue_view
+from acta.github.milestone import milestone_list
+
+
+@click.command()
+def board() -> None:
+    """Session snapshot: active work, current milestone, and backlog."""
+    branch_name = get_current_branch()
+    click.echo(f"Current branch: {branch_name}")
+    active_issue_number = get_active_issue()
+    focus_milestone_number: int | None = None
+    if active_issue_number is not None:
+        active_issue = issue_view(active_issue_number)
+        click.echo(f"Active issue: #{active_issue_number} {active_issue.title}")
+        focus_milestone_number = (
+            active_issue.milestone.number if active_issue.milestone is not None else None
+        )
+
+    milestones = milestone_list()
+    if not milestones:
+        click.echo()
+        click.echo("No open milestones.")
+        return
+
+    if focus_milestone_number is None:
+        focus_milestone_number = milestones[0].number
+    focus_milestone = next(
+        (
+            milestone_list_item
+            for milestone_list_item in milestones
+            if milestone_list_item.number == focus_milestone_number
+        ),
+        None,
+    )
+
+    if focus_milestone is not None:
+        click.echo()
+        click.echo(format_milestone_line(focus_milestone))
+        for line in format_issue_lines(issue_list(focus_milestone.number), indent="  "):
+            click.echo(line)
+
+    remaining_milestones = [
+        milestone_list_item
+        for milestone_list_item in milestones
+        if milestone_list_item.number != focus_milestone_number
+    ]
+    if remaining_milestones:
+        click.echo()
+        for milestone_list_item in remaining_milestones:
+            click.echo(format_milestone_line(milestone_list_item))

acta/cli/branch.py

@@ -0,0 +1,17 @@
+import click
+
+from acta.git.branch import fetch_origin, switch_new_branch
+from acta.git.branch import parse as parse_branch
+
+
+@click.command()
+@click.argument("name", metavar="TYPE/scope")
+def branch(name: str) -> None:
+    """Create a branch from origin/main."""
+    try:
+        parse_branch(name)
+    except ValueError as error:
+        raise click.ClickException(str(error))
+    fetch_origin()
+    switch_new_branch(name)
+    click.echo(f"Branched {name} from origin/main.")

acta/cli/commit.py

@@ -0,0 +1,64 @@
+import click
+
+from acta.cli.shared import TYPE_CHOICE, open_editor
+from acta.git.branch import get_current_branch
+from acta.git.branch import parse as parse_branch
+from acta.git.commit import add_all, push_head
+from acta.git.commit import commit as git_commit
+
+
+@click.command()
+@click.option(
+    "-A", "--stage-all", "stage_all", is_flag=True, help="Stage all changes before committing."
+)
+@click.option("-P", "--push", "push", is_flag=True, help="Push to origin after committing.")
+@click.option(
+    "-t",
+    "--type",
+    "type_override",
+    default=None,
+    metavar="TYPE",
+    type=TYPE_CHOICE,
+    help="Override the commit type inferred from the branch name.",
+)
+@click.option(
+    "-s",
+    "--scope",
+    "scope_override",
+    default=None,
+    help="Override the commit scope inferred from the branch name.",
+)
+@click.option("-b", "--body", "body", default=None, help="Commit body. Mutually exclusive with -e.")
+@click.option("-e", "--edit", "edit_body", is_flag=True, help="Open $EDITOR for commit body.")
+@click.argument("description")
+def commit(
+    stage_all: bool,
+    push: bool,
+    type_override: str | None,
+    scope_override: str | None,
+    body: str | None,
+    edit_body: bool,
+    description: str,
+) -> None:
+    """Create a conventional commit from the branch name.
+
+    Type and scope are derived from the branch. By default no body is added —
+    pass -b for an inline body, or -e to open $EDITOR. -b and -e are mutually
+    exclusive.
+    """
+    if body and edit_body:
+        raise click.UsageError("--body and --edit are mutually exclusive")
+    branch_name = get_current_branch()
+    try:
+        type_, scope = parse_branch(branch_name)
+    except ValueError as error:
+        raise click.ClickException(str(error))
+    header = f"{type_override or type_}({scope_override or scope}): {description}"
+    if edit_body:
+        body = open_editor(header)
+    if stage_all:
+        add_all()
+    git_commit(header, body)
+    if push:
+        push_head()
+        click.echo("Pushed. If a PR is open, refresh its description: gh pr edit")

acta/cli/issue.py

@@ -0,0 +1,161 @@
+import re
+
+import click
+
+from acta.cli.shared import TYPE_CHOICE, CLIGroup, open_editor
+from acta.git.branch import fetch_origin, switch_new_branch
+from acta.git.config import set_active_issue
+from acta.github.issue import (
+    IssueInfo,
+    issue_close_not_planned,
+    issue_create,
+    issue_list,
+    issue_view,
+)
+from acta.github.milestone import milestone_view
+
+
+def slugify_title(title: str) -> str:
+    """Turn an issue title into a short, branch-safe topic slug."""
+    return re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:40].rstrip("-")
+
+
+def compute_issue_column_widths(issues: list[IssueInfo]) -> tuple[int, int]:
+    """Compute column widths (number, type) wide enough to align every issue in the set."""
+    number_width = max((len(f"#{issue_info.number}") for issue_info in issues), default=1)
+    type_width = max((len(issue_info.type or "—") for issue_info in issues), default=1)
+    return number_width, type_width
+
+
+def format_issue_lines(
+    issues: list[IssueInfo],
+    indent: str = "",
+    widths: tuple[int, int] | None = None,
+) -> list[str]:
+    """Render issues as aligned lines, sorted by number.
+
+    Pass `widths` to align against a wider set than `issues` (e.g. a whole board
+    when rendering one milestone group); otherwise widths fit `issues` alone.
+    """
+    number_width, type_width = widths if widths is not None else compute_issue_column_widths(issues)
+    return [
+        f"{indent}{f'#{issue_info.number}':<{number_width}}  "
+        f"{(issue_info.type or '—'):<{type_width}}  {issue_info.title}"
+        for issue_info in sorted(issues, key=lambda issue_info: issue_info.number)
+    ]
+
+
+@click.group(cls=CLIGroup)
+def issue() -> None:
+    """Manage issues."""
+
+
+@issue.command(name="new")
+@click.argument("title")
+@click.option("--type", "type_", required=True, type=TYPE_CHOICE, help="Issue type label.")
+@click.option(
+    "--milestone",
+    "milestone_number",
+    default=None,
+    type=int,
+    metavar="NUMBER",
+    help="Milestone number.",
+)
+@click.option("-b", "--body", "body", default=None, help="Issue body. Mutually exclusive with -e.")
+@click.option("-e", "--edit", "edit_body", is_flag=True, help="Open $EDITOR for the issue body.")
+def new_issue(
+    title: str,
+    type_: str,
+    milestone_number: int | None,
+    body: str | None,
+    edit_body: bool,
+) -> None:
+    """Create a new issue."""
+    if body and edit_body:
+        raise click.UsageError("--body and --edit are mutually exclusive")
+    if edit_body:
+        body = open_editor(title)
+    number = issue_create(title, type_, body or "", milestone_number)
+    click.echo(f"Issue #{number} created.")
+
+
+@issue.command(name="list")
+@click.option(
+    "--milestone",
+    "milestone_number",
+    default=None,
+    type=int,
+    metavar="NUMBER",
+    help="Filter by milestone number.",
+)
+def list_issues(milestone_number: int | None) -> None:
+    """List open issues."""
+    issues = issue_list(milestone_number)
+    if not issues:
+        click.echo("No open issues.")
+        return
+    if milestone_number is not None:
+        for line in format_issue_lines(issues):
+            click.echo(line)
+        return
+    issues_by_milestone: dict[int | None, list[IssueInfo]] = {}
+    headers_by_milestone: dict[int | None, str] = {}
+    for issue_info in issues:
+        milestone_ref = issue_info.milestone
+        milestone_key = milestone_ref.number if milestone_ref is not None else None
+        issues_by_milestone.setdefault(milestone_key, []).append(issue_info)
+        headers_by_milestone[milestone_key] = (
+            f"#{milestone_ref.number} {milestone_ref.title}"
+            if milestone_ref is not None
+            else "No milestone"
+        )
+    widths = compute_issue_column_widths(issues)
+    is_first_group = True
+    for milestone_key in sorted(issues_by_milestone, key=lambda key: (key is None, key or 0)):
+        if not is_first_group:
+            click.echo()
+        is_first_group = False
+        click.echo(headers_by_milestone[milestone_key])
+        for line in format_issue_lines(
+            issues_by_milestone[milestone_key], indent="  ", widths=widths
+        ):
+            click.echo(line)
+
+
+@issue.command(name="start")
+@click.argument("number", type=int)
+def start_issue(number: int) -> None:
+    """Start work on an issue: create branch and record the active issue."""
+    issue_info = issue_view(number)
+    issue_type = issue_info.type
+    milestone_ref = issue_info.milestone
+    if milestone_ref is None:
+        raise click.ClickException(
+            f"Issue #{number} has no milestone — assign it to a milestone first"
+        )
+    milestone_detail = milestone_view(milestone_ref.number)
+    scope = milestone_detail.scope
+    if not scope:
+        raise click.ClickException(
+            f"Milestone #{milestone_ref.number} has no scope — "
+            "its description must start with 'scope: SCOPE'"
+        )
+    slug = slugify_title(issue_info.title)
+    topic = f"{number}-{slug}" if slug else str(number)
+    branch_name = f"{issue_type}/{scope}/{topic}"
+    fetch_origin()
+    switch_new_branch(branch_name)
+    set_active_issue(number)
+    click.echo(f"On branch {branch_name}, active issue is #{number}.")
+    issue_body = issue_info.body.strip()
+    if issue_body:
+        click.echo()
+        click.echo(issue_body)
+
+
+@issue.command(name="discard")
+@click.argument("number", type=int)
+def discard_issue(number: int) -> None:
+    """Close an issue as discarded (not planned)."""
+    issue_close_not_planned(number)
+    click.echo(f"Issue #{number} discarded.")

acta/cli/milestone.py

@@ -0,0 +1,71 @@
+import click
+
+from acta.cli.shared import CLIGroup, open_editor
+from acta.github import get_repo
+from acta.github.milestone import (
+    MilestoneListItem,
+    milestone_create,
+    milestone_list,
+    milestone_reopen,
+)
+
+
+def get_repo_name() -> str:
+    return get_repo().split("/")[-1]
+
+
+def format_milestone_line(milestone_list_item: MilestoneListItem) -> str:
+    noun = "issue" if milestone_list_item.open_issues == 1 else "issues"
+    closed = (
+        f", {milestone_list_item.closed_issues} closed" if milestone_list_item.closed_issues else ""
+    )
+    return (
+        f"#{milestone_list_item.number}  {milestone_list_item.title} — "
+        f"{milestone_list_item.open_issues} {noun} open{closed}"
+    )
+
+
+@click.group(cls=CLIGroup)
+def milestone() -> None:
+    """Manage milestones."""
+
+
+@milestone.command(name="new")
+@click.argument("title")
+@click.option("--scope", required=True, help="Scope used for branch names in this milestone.")
+@click.option(
+    "-d",
+    "--description",
+    "description",
+    default=None,
+    help="Milestone description. Mutually exclusive with -e.",
+)
+@click.option("-e", "--edit", "edit_body", is_flag=True, help="Open $EDITOR for the description.")
+def new_milestone(title: str, scope: str, description: str | None, edit_body: bool) -> None:
+    """Create a new milestone."""
+    if description and edit_body:
+        raise click.UsageError("--description and --edit are mutually exclusive")
+    if edit_body:
+        description = open_editor(title)
+    number = milestone_create(title, scope, description or "")
+    click.echo(f"Milestone #{number} created.")
+
+
+@milestone.command(name="list")
+def list_milestones() -> None:
+    """List open milestones."""
+    milestones = milestone_list()
+    if not milestones:
+        click.echo("No open milestones.")
+        return
+    click.echo(f"{get_repo_name()} milestones:")
+    for milestone_list_item in milestones:
+        click.echo(format_milestone_line(milestone_list_item))
+
+
+@milestone.command(name="reopen")
+@click.argument("number", type=int)
+def reopen_milestone(number: int) -> None:
+    """Reopen a closed milestone."""
+    milestone_reopen(number)
+    click.echo(f"Milestone #{number} reopened.")

acta/cli/pr.py

@@ -0,0 +1,140 @@
+import click
+
+from acta.cli.shared import TYPE_CHOICE, open_editor
+from acta.git.branch import (
+    delete_branch,
+    get_current_branch,
+    merge_origin_main,
+    pull_origin_main,
+    switch_branch,
+    switch_main,
+)
+from acta.git.branch import parse as parse_branch
+from acta.git.commit import push_head
+from acta.git.config import clear_active_issue, get_active_issue
+from acta.github.issue import issue_view
+from acta.github.milestone import milestone_close, milestone_view
+from acta.github.pr import pr_checks_pass, pr_checks_watch, pr_create, pr_merge, pr_view
+
+
+@click.command()
+@click.option(
+    "-t",
+    "--type",
+    "type_override",
+    default=None,
+    metavar="TYPE",
+    type=TYPE_CHOICE,
+    help="Override the PR title type inferred from the branch name.",
+)
+@click.option(
+    "-s",
+    "--scope",
+    "scope_override",
+    default=None,
+    help="Override the PR title scope inferred from the branch name.",
+)
+@click.option("-b", "--body", "body", default=None, help="PR body. Mutually exclusive with -e.")
+@click.option("-e", "--edit", "edit_body", is_flag=True, help="Open $EDITOR for the PR body.")
+@click.option(
+    "--breaking",
+    is_flag=True,
+    help="Mark a breaking change: append '!' to type(scope) per conventional commits.",
+)
+@click.argument("title")
+def pr(
+    type_override: str | None,
+    scope_override: str | None,
+    body: str | None,
+    edit_body: bool,
+    breaking: bool,
+    title: str,
+) -> None:
+    """Push branch, open a PR against main, and watch CI.
+
+    By default no body is added — pass -b for an inline body, or -e to open
+    $EDITOR. -b and -e are mutually exclusive.
+    """
+    if body and edit_body:
+        raise click.UsageError("--body and --edit are mutually exclusive")
+    branch_name = get_current_branch()
+    try:
+        type_, scope = parse_branch(branch_name)
+    except ValueError as error:
+        raise click.ClickException(str(error))
+    breaking_marker = "!" if breaking else ""
+    pr_title = f"{type_override or type_}({scope_override or scope}){breaking_marker}: {title}"
+    if edit_body:
+        body = open_editor(f"{pr_title} ({branch_name})")
+    active_issue_number = get_active_issue()
+    if active_issue_number is not None:
+        closes_footer = f"Closes #{active_issue_number}"
+        body = f"{body}\n\n{closes_footer}" if body else closes_footer
+    push_head()
+    number, url = pr_create(pr_title, body or "")
+    click.echo(url)
+    pr_checks_watch(number)
+
+
+@click.command()
+@click.option(
+    "-u",
+    "--update",
+    "update_branch",
+    default=None,
+    metavar="BRANCH",
+    help="After shipping, switch to BRANCH and merge origin/main.",
+)
+@click.option("-y", "--yes", "confirmed", is_flag=True, help="Skip confirmation prompt.")
+def ship(update_branch: str | None, confirmed: bool) -> None:
+    """Ship the PR and return to a clean main.
+
+    Squash-merges the current branch's PR, deletes the remote branch, switches
+    to local main, pulls, and force-deletes the local branch.
+    """
+    branch_name = get_current_branch()
+    if branch_name == "main":
+        raise click.ClickException("run 'acta ship' from the feature branch, not main")
+    pr_number, title = pr_view()
+    prompt = f'Ship "{title}" (#{pr_number})'
+    if update_branch:
+        prompt += f", then update {update_branch}"
+    if not confirmed:
+        click.confirm(prompt, abort=True)
+    if not pr_checks_pass(pr_number):
+        raise click.ClickException(
+            f"PR #{pr_number} has failing or pending checks — run 'acta watch' to monitor"
+        )
+    active_issue_number = get_active_issue()
+    milestone_number: int | None = None
+    if active_issue_number is not None:
+        active_issue = issue_view(active_issue_number)
+        milestone_ref = active_issue.milestone
+        if milestone_ref is not None:
+            milestone_number = milestone_ref.number
+    pr_merge(pr_number)
+    click.echo(f"Merged PR #{pr_number} {branch_name} → main")
+    switch_main()
+    pull_origin_main()
+    delete_branch(branch_name)
+    click.echo(f"Switched to main, pulled origin/main, deleted {branch_name}.")
+    if update_branch:
+        switch_branch(update_branch)
+        merge_origin_main()
+        click.echo(f"Switched to {update_branch}, merged origin/main.")
+    if active_issue_number is not None:
+        clear_active_issue()
+    if milestone_number is not None:
+        milestone_detail = milestone_view(milestone_number)
+        if milestone_detail.open_issues == 0:
+            milestone_close(milestone_number)
+            click.echo(
+                f'Milestone #{milestone_number} "{milestone_detail.title}" completed and closed.'
+            )
+
+
+@click.command()
+def watch() -> None:
+    """Watch CI checks for the current PR."""
+    number, _ = pr_view()
+    pr_checks_watch(number)

acta/cli/release.py

@@ -0,0 +1,67 @@
+from datetime import date
+
+import click
+
+from acta.git.tag import (
+    CALVER,
+    SEMVER,
+    Scheme,
+    compute_next_calver,
+    create_tag,
+    detect_scheme,
+    fetch_tags,
+    list_tags,
+    next_release_tag,
+)
+
+
+@click.command()
+@click.option(
+    "--scheme",
+    "scheme",
+    type=click.Choice([CALVER, SEMVER], case_sensitive=False),
+    default=None,
+    help="Versioning scheme: calver (vYYYY.MM.N) or semver (vMAJOR.MINOR.PATCH).",
+)
+@click.option(
+    "--stable", is_flag=True, help="Promote a 0.x project to v1.0.0 (SemVer only, one-time)."
+)
+@click.option("-y", "--yes", "confirmed", is_flag=True, help="Skip confirmation prompt.")
+def release(scheme: Scheme | None, stable: bool, confirmed: bool) -> None:
+    """Tag origin/main and push the tag.
+
+    The SemVer bump is derived from the conventional-commit subjects since the last
+    tag: a `feat` (or, once stable, a `!` breaking change) bumps minor (major when
+    stable); anything else, patch. While still 0.x a breaking change is capped at
+    minor — pass --stable for the deliberate one-time jump to v1.0.0.
+    """
+    fetch_tags()
+    existing_tags = list_tags()
+    if not scheme:
+        try:
+            scheme = detect_scheme(existing_tags)
+        except ValueError as error:
+            raise click.ClickException(str(error))
+    if not scheme:
+        click.echo("No existing tags found. Choose a versioning scheme:")
+        click.echo(
+            f"  {CALVER}   vYYYY.MM.N         — calendar versioning, counter resets each month"
+        )
+        click.echo(f"  {SEMVER}   vMAJOR.MINOR.PATCH — semantic versioning")
+        scheme_input = click.prompt(
+            "Scheme", type=click.Choice([CALVER, SEMVER], case_sensitive=False), show_choices=False
+        )
+        scheme = CALVER if scheme_input == CALVER else SEMVER
+    if stable and scheme == CALVER:
+        raise click.ClickException("--stable applies to SemVer only")
+    if scheme == CALVER:
+        tag = compute_next_calver(existing_tags, date.today())
+    else:
+        try:
+            tag = next_release_tag(existing_tags, stable)
+        except ValueError as error:
+            raise click.ClickException(str(error))
+    if not confirmed:
+        click.confirm(f"Tag and push {tag}", abort=True)
+    create_tag(tag)
+    click.echo(f"Tagged and pushed {tag}")

acta/cli/shared.py

@@ -0,0 +1,45 @@
+import subprocess
+import sys
+
+import click
+
+from acta.git.branch import TYPES
+
+
+class CLIGroup(click.Group):
+    def invoke(self, ctx: click.Context) -> object:
+        try:
+            return super().invoke(ctx)
+        except (click.exceptions.Exit, click.exceptions.Abort):
+            raise  # Click's own control flow (--help, ctrl-C); both subclass RuntimeError
+        except subprocess.CalledProcessError as error:
+            if error.stderr:
+                click.echo(error.stderr, err=True, nl=False)
+            sys.exit(error.returncode)
+        except RuntimeError as error:
+            raise click.ClickException(str(error)) from error
+
+
+def strip_comments(text: str) -> str:
+    lines = [line for line in text.splitlines() if not line.startswith("#")]
+    collapsed: list[str] = []
+    prev_blank = False
+    for line in lines:
+        blank = not line.strip()
+        if blank and prev_blank:
+            continue
+        collapsed.append(line)
+        prev_blank = blank
+    return "\n".join(collapsed).strip()
+
+
+def open_editor(hint: str) -> str:
+    template = f"# {hint}\n# Lines starting with '#' are ignored.\n\n"
+    edited_text = click.edit(template)
+    body_text = strip_comments(edited_text or "")
+    if not body_text:
+        raise click.Abort()
+    return body_text
+
+
+TYPE_CHOICE = click.Choice(sorted(TYPES))

acta/git/__init__.py

@@ -0,0 +1,27 @@
+import subprocess
+
+
+def git(*args: str, capture: bool = False, quiet: bool = False) -> str:
+    """Run a git command.
+
+    `capture` returns stdout. `quiet` suppresses stdout and stderr on success; on
+    failure the captured stderr rides along on the raised CalledProcessError so the
+    error is still surfaced (see CLIGroup).
+    """
+    try:
+        completed_process = subprocess.run(
+            ["git", *args],
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE if (capture or quiet) else None,
+            stderr=subprocess.PIPE if quiet else None,
+        )
+        return completed_process.stdout.strip() if completed_process.stdout else ""
+    except FileNotFoundError:
+        raise RuntimeError("'git' not found in PATH — install git: https://git-scm.com/install/")
+    except subprocess.CalledProcessError:
+        raise
+
+
+def get_remote_url(remote_name: str) -> str:
+    return git("remote", "get-url", remote_name, capture=True)