git-acta 1.0.0__tar.gz → 1.1.0__tar.gz

git_acta-1.1.0/CLAUDE.md

@@ -0,0 +1,19 @@
+# git-acta
+
+Structured git workflow CLI: conventional commits, trunk-based branches, GitHub PR lifecycle. Thin Click CLI (`src/acta/cli/`) over git (`src/acta/git/`) and GitHub (`src/acta/github/`) helpers; every subprocess call routes through the `git()`/`gh()` wrappers.
+
+## MUST DO — enforce on every task without exception
+
+**MUST BE OPINIONATED, NOT SYCOPHANTIC.** Push back on bad ideas; explain the better path instead of silently complying.
+
+**MUST DOGFOOD `acta` PER `CONTRIBUTING.md`.** Drive every branch/commit/PR/ship through `acta`, never raw `git`/`gh` for those steps.
+
+**MUST APPLY DESIGN PRINCIPLES ON EVERY CHANGE.** KISS, YAGNI, DRY, less-is-more, Unix do-one-thing.
+
+**MUST DOCSTRING EVERY FUNCTION (Google style).** One line minimum; full Args/Returns/Raises plus a behavioral example for non-obvious ones. A wrapper's docstring states what its underlying `git`/`gh` command does and why.
+
+**MUST TYPE EVERYTHING AND KEEP PYRIGHT-STRICT CLEAN.** Full annotations, no implicit `Any`.
+
+**MUST TEST EVERY BEHAVIOR CHANGE.** pytest with `pytest-subprocess`: real `git` against a temp repo, `gh` faked via `fp.register`. Mirror the existing `tests/` patterns. Use `uv run pytest` to run the tests.
+
+**LINT AND TYPES RUN ON COMMIT** (ruff + pyright via the pre-commit hook) — rely on the hook, don't run them manually.

git_acta-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+git-acta is developed with itself — branches, commits, and PRs all go through `acta`.
+
+## Workflow
+
+### Baseline
+
+```sh
+acta branch type/scope
+acta commit -A "Description" -b "Context for why."  # -A stages everything before committing
+acta pr "PR title" -b "What changed and why."
+acta ship -y
+```
+
+Descriptions are not optional, they keep the repo self-documenting. The PR title
+and body are what land on `main` and feed the release notes. Commit bodies get
+squashed away on merge, so skip them by default.
+
+### Variations
+
+```sh
+git add path/a path/b && acta commit "Title"  # stage selectively (-A stages everything)
+acta commit -AP "Title"                       # stage all + commit + push (follow-up on an open PR)
+acta commit -t chore "Title"                  # override the type inferred from the branch
+```
+
+## PR body template
+
+Base PR bodies on this structure. The `## Breaking` section is optional — include
+it only for breaking changes:
+
+```markdown
+One-line summary of the change.
+
+## Changes
+- What changed, point by point
+
+## Why
+The motivation and context behind the change.
+
+## Breaking
+What breaks and the step users must take. (Omit for non-breaking changes.)
+```

{git_acta-1.0.0 → git_acta-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-acta
-Version: 1.0.0
+Version: 1.1.0
 Summary: Structured git workflow CLI: conventional commits, trunk-based branches, GitHub PR lifecycle
 Project-URL: Homepage, https://github.com/nicobc/git-acta
 Project-URL: Source, https://github.com/nicobc/git-acta

git_acta-1.1.0/RELEASING.md

@@ -0,0 +1,11 @@
+# Releasing
+
+git-acta publishes SemVer-tagged releases to PyPI. Pushing a `v*.*.*` tag fires the publish workflow. Git tags are the source of truth for the version; `pyproject.toml` mirrors the latest tag.
+
+## Release script
+
+Once ready to tag a new release, run
+```sh
+uv run scripts/release.py            # version derived from the commits since the last tag
+uv run scripts/release.py --stable   # one-time promotion of a 0.x project to v1.0.0
+```

{git_acta-1.0.0 → git_acta-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "git-acta"
-version = "1.0.0"
+version = "1.1.0"
 description = "Structured git workflow CLI: conventional commits, trunk-based branches, GitHub PR lifecycle"
 readme = "README.md"
 license = "MIT"

{git_acta-1.0.0 → git_acta-1.1.0}/scripts/release.py

@@ -18,7 +18,8 @@ import subprocess
 import time
 from pathlib import Path
 
-from acta.git.tag import fetch_tags, list_tags, next_release_tag
+from acta.git.commit import get_commit_subjects
+from acta.git.tag import fetch_tags, latest_semver_tag, list_tags, next_release_tag
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 PYPROJECT = REPO_ROOT / "pyproject.toml"
@@ -78,6 +79,19 @@ def wait_for_publish_run(tag: str, commit_sha: str) -> str:
     )
 
 
+def _describe_bump(latest: str | None, new_tag: str) -> str:
+    """Describe the jump from ``latest`` to ``new_tag`` as major/minor/patch."""
+    if latest is None:
+        return "initial release"
+    old_major, old_minor, _ = (int(part) for part in latest[1:].split("."))
+    new_major, new_minor, _ = (int(part) for part in new_tag[1:].split("."))
+    if new_major > old_major:
+        return "major"
+    if new_minor > old_minor:
+        return "minor"
+    return "patch"
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description="Derive the version, ship, tag, and publish.")
     parser.add_argument(
@@ -93,18 +107,24 @@ def main() -> None:
     dry_run: bool = args.dry_run
 
     fetch_tags()
+    existing_tags = list_tags()
     try:
-        new_tag = next_release_tag(list_tags(), stable)
+        new_tag = next_release_tag(existing_tags, stable)
     except ValueError as error:
         raise SystemExit(f"release: {error}")
     new_version = new_tag.removeprefix("v")
     title = f"bump version to {new_version}"
 
     if dry_run:
-        print(f"release: would tag {new_tag}")
-        print(f"  set pyproject.toml + uv.lock to {new_version}")
-        print(f'  acta branch/commit/pr/ship for "{title}"')
-        print(f"  acta release{' --stable' if stable else ''} -y, then watch the publish job")
+        latest = latest_semver_tag(existing_tags)
+        print("release: dry run — no changes made")
+        print(f"  current version: {latest or '(none)'}")
+        if latest is not None:
+            print(f"  commits since {latest}:")
+            for subject in get_commit_subjects(f"{latest}..origin/main"):
+                print(f"    {subject}")
+        print(f"  bump: {_describe_bump(latest, new_tag)} → {new_tag}")
+        print(f"  on a real run: ship the bump, push {new_tag}, and publish to PyPI")
         return
 
     write_pyproject_version(new_version)

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/__init__.py

@@ -1,3 +1,5 @@
+"""The ``acta`` command group and subcommand registration."""
+
 import click
 
 from acta.cli.board import board

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/board.py

@@ -1,3 +1,5 @@
+"""``acta board`` — a session snapshot of active work and milestones."""
+
 import click
 
 from acta.cli.issue import format_issue_lines

git_acta-1.1.0/src/acta/cli/branch.py

@@ -0,0 +1,25 @@
+"""``acta branch`` — create a type/scope branch from origin/main."""
+
+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 `type/scope` branch from the latest origin/main.
+
+    Fetches origin, then branches off origin/main. The name sets the
+    conventional-commit type and scope that `acta commit` and `acta pr` reuse —
+    `feat/auth` produces `feat(auth): ...` messages. An optional third segment
+    (`type/scope/topic`) adds a human-readable topic without changing type or scope.
+    """
+    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.")

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/commit.py

@@ -1,6 +1,8 @@
+"""``acta commit`` — create a conventional commit from the branch name."""
+
 import click
 
-from acta.cli.shared import TYPE_CHOICE, open_editor
+from acta.cli.shared import TYPE_CHOICE, open_editor, strip_type_prefix
 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
@@ -53,7 +55,9 @@ def commit(
         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}"
+    header = (
+        f"{type_override or type_}({scope_override or scope}): {strip_type_prefix(description)}"
+    )
     if edit_body:
         body = open_editor(header)
     if stage_all:

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/issue.py

@@ -1,3 +1,5 @@
+"""``acta issue`` — create, list, start, and discard GitHub issues."""
+
 import re
 
 import click
@@ -47,7 +49,7 @@ def format_issue_lines(
 
 @click.group(cls=CLIGroup)
 def issue() -> None:
-    """Manage issues."""
+    """Create, list, start, and discard issues on the GitHub board."""
 
 
 @issue.command(name="new")
@@ -70,7 +72,11 @@ def new_issue(
     body: str | None,
     edit_body: bool,
 ) -> None:
-    """Create a new issue."""
+    """Create a GitHub issue with a type label and optional milestone.
+
+    The --type becomes a `type: ...` label; when you later run `acta issue start`,
+    that label sets the new branch's conventional-commit type.
+    """
     if body and edit_body:
         raise click.UsageError("--body and --edit are mutually exclusive")
     if edit_body:
@@ -89,7 +95,10 @@ def new_issue(
     help="Filter by milestone number.",
 )
 def list_issues(milestone_number: int | None) -> None:
-    """List open issues."""
+    """List open issues, grouped by milestone.
+
+    With --milestone, lists only that milestone's issues as a flat list.
+    """
     issues = issue_list(milestone_number)
     if not issues:
         click.echo("No open issues.")

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/milestone.py

@@ -1,3 +1,5 @@
+"""``acta milestone`` — create, list, and reopen GitHub milestones."""
+
 import click
 
 from acta.cli.shared import CLIGroup, open_editor
@@ -11,10 +13,12 @@ from acta.github.milestone import (
 
 
 def get_repo_name() -> str:
+    """Return just the repository name (the ``repo`` half of ``owner/repo``)."""
     return get_repo().split("/")[-1]
 
 
 def format_milestone_line(milestone_list_item: MilestoneListItem) -> str:
+    """Render a milestone as a one-line summary with its open (and closed) issue counts."""
     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 ""
@@ -27,7 +31,7 @@ def format_milestone_line(milestone_list_item: MilestoneListItem) -> str:
 
 @click.group(cls=CLIGroup)
 def milestone() -> None:
-    """Manage milestones."""
+    """Create, list, and reopen milestones on the GitHub board."""
 
 
 @milestone.command(name="new")
@@ -42,7 +46,10 @@ def milestone() -> None:
 )
 @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."""
+    """Create a milestone whose --scope sets the branch scope for its issues.
+
+    Each issue started under it branches as `type/<scope>/N-title`.
+    """
     if description and edit_body:
         raise click.UsageError("--description and --edit are mutually exclusive")
     if edit_body:

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/pr.py

@@ -1,10 +1,13 @@
+"""``acta pr``, ``ship``, and ``watch`` — the pull-request lifecycle."""
+
 import click
 
-from acta.cli.shared import TYPE_CHOICE, open_editor
+from acta.cli.shared import TYPE_CHOICE, open_editor, strip_type_prefix
 from acta.git.branch import (
     delete_branch,
     get_current_branch,
     merge_origin_main,
+    prune_origin,
     pull_origin_main,
     switch_branch,
     switch_main,
@@ -63,7 +66,10 @@ def pr(
     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}"
+    pr_title = (
+        f"{type_override or type_}({scope_override or scope}){breaking_marker}: "
+        f"{strip_type_prefix(title)}"
+    )
     if edit_body:
         body = open_editor(f"{pr_title} ({branch_name})")
     active_issue_number = get_active_issue()
@@ -117,7 +123,10 @@ def ship(update_branch: str | None, confirmed: bool) -> None:
     switch_main()
     pull_origin_main()
     delete_branch(branch_name)
-    click.echo(f"Switched to main, pulled origin/main, deleted {branch_name}.")
+    prune_origin()
+    click.echo(
+        f"Switched to main, pulled origin/main, deleted {branch_name}, and pruned stale refs."
+    )
     if update_branch:
         switch_branch(update_branch)
         merge_origin_main()

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/cli/release.py

@@ -1,3 +1,5 @@
+"""``acta release`` — compute and push the next version tag."""
+
 from datetime import date
 
 import click

git_acta-1.1.0/src/acta/cli/shared.py

@@ -0,0 +1,86 @@
+"""Shared CLI helpers: error handling, editor input, and title/body utilities."""
+
+import re
+import subprocess
+import sys
+
+import click
+
+from acta.git.branch import TYPES
+
+# A leading conventional-commit prefix: type, optional (scope), optional !, colon.
+_TYPE_PREFIX_RE = re.compile(rf"^(?:{'|'.join(sorted(TYPES))})(?:\([^)]*\))?!?:\s*")
+
+
+class CLIGroup(click.Group):
+    """Click group that turns subprocess and runtime failures into clean CLI errors."""
+
+    def invoke(self, ctx: click.Context) -> object:
+        """Run the subcommand, mapping failures to tidy exit codes and messages.
+
+        A failed `git`/`gh` subprocess exits with its own return code, echoing its
+        stderr; other RuntimeErrors become a one-line ClickException. Click's own
+        --help/abort control flow is re-raised untouched.
+        """
+        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:
+    """Drop HTML-comment hint lines from editor input and collapse blank-line runs.
+
+    Used to clean text returned from $EDITOR: removes full-line ``<!-- ... -->``
+    hints and squeezes consecutive blank lines, leaving a trimmed body. ``#`` is
+    deliberately not the marker — it is a Markdown heading, and these bodies
+    render as Markdown on GitHub.
+    """
+    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:
+    """Open $EDITOR with a hint header and return the entered body, comments stripped.
+
+    Args:
+        hint: Shown as a leading ``<!-- hint -->`` comment to orient the writer.
+
+    Returns:
+        The cleaned body text.
+
+    Raises:
+        click.Abort: If the body is empty after stripping comments.
+    """
+    template = f"<!-- {hint} -->\n<!-- HTML comments 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
+
+
+def strip_type_prefix(title: str) -> str:
+    """Drop a redundant leading conventional-commit prefix from a caller title.
+
+    acta derives type(scope) from the branch and prepends it, so a prefix the
+    caller typed (e.g. 'fix: x' or 'fix(auth)!: x') would otherwise double up.
+    """
+    return _TYPE_PREFIX_RE.sub("", title, count=1)
+
+
+TYPE_CHOICE = click.Choice(sorted(TYPES))

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/git/__init__.py

@@ -1,3 +1,5 @@
+"""Thin wrappers around the git command-line tool."""
+
 import subprocess
 
 
@@ -24,4 +26,5 @@ def git(*args: str, capture: bool = False, quiet: bool = False) -> str:
 
 
 def get_remote_url(remote_name: str) -> str:
+    """Return the configured URL of the named remote (e.g. ``origin``)."""
     return git("remote", "get-url", remote_name, capture=True)

git_acta-1.1.0/src/acta/git/branch.py

@@ -0,0 +1,123 @@
+import re
+
+from acta.git import git
+
+TYPES = frozenset(
+    [
+        "build",
+        "chore",
+        "ci",
+        "docs",
+        "feat",
+        "fix",
+        "perf",
+        "refactor",
+        "revert",
+        "style",
+        "test",
+    ]
+)
+
+# type/scope, with an optional third descriptive segment (e.g. an issue topic);
+# the conventional-commit type and scope are derived from the first two.
+_BRANCH_RE = re.compile(r"([^/]+)/([^/]+)(?:/.+)?")
+_SCOPE_RE = re.compile(r"[a-z0-9][a-z0-9_-]*", re.IGNORECASE)
+
+
+def parse(branch: str) -> tuple[str, str]:
+    """Extract the conventional-commit type and scope from a branch name.
+
+    Branch names follow ``type/scope`` with an optional third descriptive
+    segment (``type/scope/topic``); only the first two segments are significant.
+
+    Args:
+        branch: Branch name to parse, e.g. ``fix/auth`` or ``feat/auth/sso``.
+
+    Returns:
+        The ``(type, scope)`` pair.
+
+    Raises:
+        ValueError: If the name doesn't match ``type/scope``, the type is not a
+            conventional-commit type, or the scope has invalid characters.
+
+    Example:
+        >>> parse("feat/auth/sso")
+        ('feat', 'auth')
+    """
+    branch_match = _BRANCH_RE.fullmatch(branch)
+    if not branch_match:
+        raise ValueError(f"Branch '{branch}' does not follow type/scope convention")
+    type_ = branch_match.group(1)
+    if type_ not in TYPES:
+        raise ValueError(
+            f"'{type_}' is not a conventional commit type. Use one of: {', '.join(sorted(TYPES))}"
+        )
+    scope = branch_match.group(2)
+    if not _SCOPE_RE.fullmatch(scope):
+        raise ValueError(
+            f"'{scope}' is not a valid scope. Use letters, digits, hyphens, and underscores."
+        )
+    return type_, scope
+
+
+def get_current_branch() -> str:
+    """Return the name of the currently checked-out branch."""
+    return git("branch", "--show-current", capture=True)
+
+
+def fetch_origin() -> None:
+    """Download the latest state from origin and clean up stale branch pointers.
+
+    Git keeps a local read-only pointer for each branch on origin, named
+    ``origin/<branch>`` (a "remote-tracking ref") — its snapshot of where that
+    branch was at the last fetch. ``--prune`` deletes the pointers for branches
+    that have since been removed on origin (for example after their PR merged),
+    so they don't pile up and shadow names a new branch may want to reuse.
+    """
+    git("fetch", "--prune", "origin", quiet=True)
+
+
+def prune_origin() -> None:
+    """Delete local pointers to branches that no longer exist on origin.
+
+    Like the prune half of ``fetch_origin`` but without downloading anything:
+    it only removes the local ``origin/<branch>`` pointers whose branch is gone
+    on origin. Used right after merging a PR (whose branch was deleted) to keep
+    the local view in sync.
+    """
+    git("remote", "prune", "origin", quiet=True)
+
+
+def switch_new_branch(name: str) -> None:
+    """Create branch ``name`` from origin/main and check it out."""
+    git("switch", "-c", name, "origin/main", quiet=True)
+
+
+def switch_main() -> None:
+    """Check out the main branch."""
+    git("switch", "main", quiet=True)
+
+
+def pull_origin_main() -> None:
+    """Update the current branch with the latest commits from origin/main."""
+    git("pull", "origin", "main", quiet=True)
+
+
+def branch_exists(name: str) -> bool:
+    """Return True if a local branch named ``name`` exists."""
+    return bool(git("branch", "--list", name, capture=True))
+
+
+def delete_branch(name: str) -> None:
+    """Force-delete the local branch ``name``, discarding unmerged commits."""
+    git("branch", "-D", name, quiet=True)
+
+
+def switch_branch(name: str) -> None:
+    """Check out the existing branch ``name``."""
+    git("switch", name, quiet=True)
+
+
+def merge_origin_main() -> None:
+    """Merge origin/main into the current branch."""
+    git("merge", "origin/main", quiet=True)

git_acta-1.1.0/src/acta/git/commit.py

@@ -0,0 +1,26 @@
+"""Staging, committing, and pushing helpers."""
+
+from acta.git import git
+
+
+def add_all() -> None:
+    """Stage every change in the working tree (tracked, new, and deleted)."""
+    git("add", "-A")
+
+
+def commit(header: str, body: str | None = None) -> None:
+    """Create a commit with ``header`` as the subject and an optional ``body`` paragraph."""
+    commit_args = ["commit", "-m", header]
+    if body:
+        commit_args += ["-m", body]
+    git(*commit_args)
+
+
+def push_head() -> None:
+    """Push the current branch to origin, setting it as the upstream to track."""
+    git("push", "--set-upstream", "origin", "HEAD", quiet=True)
+
+
+def get_commit_subjects(rev_range: str) -> list[str]:
+    """Return the subject line of each commit in ``rev_range`` (e.g. ``v1.0.0..origin/main``)."""
+    return git("log", rev_range, "--format=%s", capture=True).splitlines()

{git_acta-1.0.0 → git_acta-1.1.0}/src/acta/git/config.py

@@ -1,9 +1,12 @@
+"""Track the active issue in local git config (key ``clerk.active-issue``)."""
+
 import subprocess
 
 from acta.git import git
 
 
 def get_active_issue() -> int | None:
+    """Return the issue number recorded for this repo, or None if none is set."""
     try:
         config_value = git("config", "--get", "clerk.active-issue", capture=True)
         return int(config_value) if config_value else None
@@ -12,10 +15,12 @@ def get_active_issue() -> int | None:
 
 
 def set_active_issue(number: int) -> None:
+    """Record ``number`` as the active issue, so ``acta pr`` can append ``Closes #N``."""
     git("config", "clerk.active-issue", str(number))
 
 
 def clear_active_issue() -> None:
+    """Remove the active-issue record; a no-op if none is set."""
     try:
         git("config", "--unset", "clerk.active-issue")
     except subprocess.CalledProcessError: