afterpython 0.1.0.dev7__py3-none-any.whl → 0.1.0.dev9__py3-none-any.whl

afterpython/cli/main.py

@@ -1,32 +1,89 @@
 import os
 import subprocess
+from collections import defaultdict
 
 import click
+from dotenv import find_dotenv, load_dotenv
 from trogon import tui
-from dotenv import load_dotenv, find_dotenv
 
 import afterpython as ap
 from afterpython import __version__
-from afterpython.cli.commands.init import init
+from afterpython.cli.commands.add import add
 from afterpython.cli.commands.build import build
-from afterpython.cli.commands.dev import dev
-from afterpython.cli.commands.update import update
+from afterpython.cli.commands.bump import bump
 from afterpython.cli.commands.check import check
-from afterpython.cli.commands.install import install
-from afterpython.cli.commands.format import format
-from afterpython.cli.commands.sync import sync
-from afterpython.cli.commands.start import start, doc, blog, tutorial, example, guide
-from afterpython.cli.commands.preview import preview
 from afterpython.cli.commands.clean import clean
-from afterpython.cli.commands.pre_commit import pre_commit
-from afterpython.cli.commands.commitizen import commitizen
 from afterpython.cli.commands.commit import commit
-from afterpython.cli.commands.bump import bump
+from afterpython.cli.commands.commitizen import commitizen
+from afterpython.cli.commands.dev import dev
+from afterpython.cli.commands.format import format
+from afterpython.cli.commands.init import init
+from afterpython.cli.commands.init_branch_rules import init_branch_rules
+from afterpython.cli.commands.install import install
+from afterpython.cli.commands.lock import lock
+from afterpython.cli.commands.pre_commit import pre_commit
+from afterpython.cli.commands.preview import preview
 from afterpython.cli.commands.release import release
+from afterpython.cli.commands.remove import remove
+from afterpython.cli.commands.start import blog, doc, example, guide, start, tutorial
+from afterpython.cli.commands.sync import sync
+from afterpython.cli.commands.update import update
+
+
+class AliasGroup(click.Group):
+    """Custom group that displays command aliases together."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._aliases = defaultdict(list)  # Maps primary command -> list of aliases
+        self._alias_to_primary = {}  # Maps alias -> primary command name
+
+    def add_command(self, cmd, name=None):
+        """Track aliases when the same command is added with different names."""
+        name = name or cmd.name
+
+        # Check if this command object was already added under a different name
+        for existing_name, existing_cmd in self.commands.items():
+            if existing_cmd is cmd and existing_name != name:
+                # This is an alias
+                self._aliases[existing_name].append(name)
+                self._alias_to_primary[name] = existing_name
+                break
+
+        super().add_command(cmd, name)
+
+    def format_commands(self, ctx, formatter):
+        """Format commands with aliases shown together."""
+        commands = []
+        for subcommand in self.list_commands(ctx):
+            # Skip aliases - they'll be shown with their primary command
+            if subcommand in self._alias_to_primary:
+                continue
+
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None:
+                continue
+
+            # Skip hidden commands
+            if cmd.hidden:
+                continue
+
+            help_text = cmd.get_short_help_str(limit=formatter.width)
+
+            # Build command name with aliases
+            aliases = self._aliases.get(subcommand, [])
+            if aliases:
+                subcommand = f"{subcommand}, {', '.join(aliases)}"
+
+            commands.append((subcommand, help_text))
+
+        if commands:
+            with formatter.section("Commands"):
+                formatter.write_dl(commands)
 
 
 @tui(command="tui", help="Open terminal UI")
-@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.group(cls=AliasGroup, context_settings={"help_option_names": ["-h", "--help"]})
 @click.pass_context
 @click.version_option(version=__version__)
 def afterpython_group(ctx):
@@ -50,6 +107,7 @@ afterpython_group.add_command(build)
 afterpython_group.add_command(dev)
 afterpython_group.add_command(update)
 afterpython_group.add_command(check)
+afterpython_group.add_command(check, name="lint")
 afterpython_group.add_command(format)
 afterpython_group.add_command(sync)
 afterpython_group.add_command(start)
@@ -63,9 +121,12 @@ afterpython_group.add_command(preview)
 afterpython_group.add_command(clean)
 afterpython_group.add_command(pre_commit)
 afterpython_group.add_command(pre_commit, name="pc")
-afterpython_group.add_command(pre_commit, name="precommit")
 afterpython_group.add_command(commitizen)
 afterpython_group.add_command(commitizen, name="cz")
 afterpython_group.add_command(commit)
 afterpython_group.add_command(bump)
 afterpython_group.add_command(release)
+afterpython_group.add_command(init_branch_rules)
+afterpython_group.add_command(add)
+afterpython_group.add_command(remove)
+afterpython_group.add_command(lock)

afterpython/const.py

@@ -1,5 +1,4 @@
 from afterpython._typing import tContentType
 
-
 NODEENV_VERSION = "24.11.0"
 CONTENT_TYPES: set[tContentType] = {"doc", "blog", "tutorial", "example", "guide"}

afterpython/pcu.py

@@ -3,7 +3,8 @@ pcu = "pip check updates", similar to ncu (npm check updates in Node.js)
 """
 
 from __future__ import annotations
-from typing import TYPE_CHECKING, TypedDict, NamedTuple, TypeAlias
+
+from typing import TYPE_CHECKING, NamedTuple, TypeAlias, TypedDict
 
 if TYPE_CHECKING:
     from tomlkit.toml_document import TOMLDocument
@@ -60,6 +61,7 @@ async def get_latest_versions(
 ) -> dict[str, Version | None]:
     """Get latest versions for a list of dependencies from PyPI."""
     import httpx
+
     from afterpython.utils import fetch_pypi_json
 
     async def fetch_version(

afterpython/templates/ci-workflow-template.yml

@@ -0,0 +1,197 @@
+name: CI
+
+# Trigger CI on pushes to main and all pull requests
+# This ensures every code change is validated before merging
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    # Run on all PRs regardless of target branch
+    branches:
+      - '**'
+
+jobs:
+  # Job 1: Lint and Format Check
+  # Runs ruff to check code quality and formatting
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        # Install the package with uv in system mode
+        # This installs ruff and other tools defined in dependencies
+        run: uv pip install --system .
+
+      - name: Run ruff check
+        run: ruff check --config ./afterpython/ruff.toml .
+
+      - name: Run ruff format check
+        # --check flag ensures it only validates, doesn't reformat
+        run: ruff format --check --config ./afterpython/ruff.toml .
+
+  # Job 2: Detect Test Strategy
+  # Determines whether to use pixi or uv based on pixi.toml presence
+  detect-test-strategy:
+    runs-on: ubuntu-latest
+    outputs:
+      use_pixi: ${{ steps.check.outputs.use_pixi }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Check for pixi.toml
+        id: check
+        run: |
+          if [ -f "pixi.toml" ]; then
+            echo "use_pixi=true" >> $GITHUB_OUTPUT
+          else
+            echo "use_pixi=false" >> $GITHUB_OUTPUT
+          fi
+
+  # Job 3.1: Test Suite - UV Workflow
+  # Traditional Python testing with uv for projects without pixi
+  test-uv:
+    needs: detect-test-strategy
+    if: needs.detect-test-strategy.outputs.use_pixi == 'false'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+      # TODO: support python 3.14
+        python-version: ['3.11', '3.12', '3.13']
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          # Install package, main dependencies, and test dependencies
+          # If no [dependency-groups] test exists, only the package and main dependencies are installed
+          uv pip install --system . --group test || uv pip install --system .
+
+      - name: Run tests with pytest
+        # Run pytest with verbose output
+        # Exit code 5 (no tests collected) is treated as success
+        run: |
+          pytest -v || if [ $? -eq 5 ]; then exit 0; else exit $?; fi
+
+  # Job 3.2: Test Suite - Pixi Workflow
+  # Pixi-based testing for projects using pixi.toml
+  test-pixi:
+    needs: detect-test-strategy
+    if: needs.detect-test-strategy.outputs.use_pixi == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+      # TODO: support python 3.14
+        environment: ['py311', 'py312', 'py313']
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up pixi
+        uses: prefix-dev/setup-pixi@v0.9.3
+        with:
+          pixi-version: v0.59.0
+          cache: true
+          # Optional: Uncomment if you need prefix.dev authentication
+          # auth-host: prefix.dev
+          # auth-token: ${{ secrets.PREFIX_DEV_TOKEN }}
+
+      - name: Run tests with pixi
+        # Runs test in specific Python environment (py311, py312, py313)
+        # Assumes you have environments defined in pixi.toml with a "test" task
+        # Example pixi.toml:
+        #   [environments]
+        #   py311 = ["py311", "test"]
+        #   [feature.test.tasks]
+        #   test = "pytest -v"
+        # Note: Exit code 5 (no tests collected) is treated as success
+        run: |
+          pixi run -e ${{ matrix.environment }} test || if [ $? -eq 5 ]; then exit 0; else exit $?; fi
+
+  # Job 3.3: Test Suite - Complete
+  # Unified test status for branch protection
+  test:
+    if: always()
+    needs: [detect-test-strategy, test-uv, test-pixi]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check test results
+        run: |
+          uv_result="${{ needs.test-uv.result }}"
+          pixi_result="${{ needs.test-pixi.result }}"
+          # One should succeed, the other should be skipped
+          if [ "$uv_result" == "success" ] || [ "$uv_result" == "skipped" ]; then
+            if [ "$pixi_result" == "success" ] || [ "$pixi_result" == "skipped" ]; then
+              echo "All tests passed!"
+              exit 0
+            fi
+          fi
+          echo "Tests failed: uv=$uv_result, pixi=$pixi_result"
+          exit 1
+
+  # Job 4: Build Verification
+  # Ensures the package can be built successfully
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: List build artifacts
+        # Show what was built (wheel + sdist)
+        # Useful for debugging build issues
+        run: ls -lh dist/
+
+      - name: Install built package
+        # Test that the built wheel can be installed
+        # This catches packaging issues like missing files
+        run: uv pip install --system dist/*.whl
+
+      - name: Verify installation
+        # Confirm the CLI entry point works
+        # This ensures the package is usable after installation
+        run: ap --help
+
+  # Job 5: Type Check
+  # typecheck:

afterpython/templates/dependabot-template.yml

@@ -0,0 +1,30 @@
+# Dependabot configuration for automatic dependency updates
+# See: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Update GitHub Actions versions
+  # This keeps your workflow actions secure and up-to-date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates monthly (less noisy than weekly)
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    # Group all GitHub Actions updates into a single PR
+    # This reduces PR noise and makes reviewing easier
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    # Automatically add reviewers (optional - uncomment and customize)
+    # reviewers:
+    #   - "your-username"
+    # Limit how many Dependabot PRs can be open at once (optional)
+    # Default is 5, increase if you want more concurrent PRs
+    # open-pull-requests-limit: 10
+    #
+    # Note: Auto-merge is configured in GitHub repo settings, not here.
+    # Go to: Settings → General → Pull Requests → Allow auto-merge

afterpython/templates/deploy-workflow-template.yml

@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -43,19 +43,19 @@ jobs:
           version: 10
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: '24'
           cache: 'pnpm'
           cache-dependency-path: './afterpython/_website/pnpm-lock.yaml'
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: "latest"
 
@@ -71,7 +71,7 @@ jobs:
           ap build
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: './afterpython/_website/build'
 

afterpython/templates/release-workflow-template.yml

@@ -14,15 +14,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: "latest"
 

afterpython/templates/ruff-template.toml

@@ -18,7 +18,7 @@ ignore = [
 ]
 # extended rules:
 extend-select = [
-    # "I",     # isort - import sorting
+    "I",     # isort - import sorting
     "UP",    # pyupgrade - upgrade syntax for newer Python
     "B",     # flake8-bugbear - find likely bugs
     "SIM",   # flake8-simplify - simplify code

afterpython/tools/_afterpython.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -7,7 +8,7 @@ if TYPE_CHECKING:
 import tomlkit
 
 import afterpython as ap
-from afterpython._io.toml import read_toml, write_toml, _to_tomlkit
+from afterpython._io.toml import _to_tomlkit, read_toml, write_toml
 
 
 def read_afterpython() -> TOMLDocument:

afterpython/tools/_git.py

@@ -58,7 +58,7 @@ def get_github_url() -> str | None:
         return None
 
 
-def setup_github_auth():
+def is_gh_authenticated():
     """Guide user through GitHub authentication."""
     if not has_gh():
         print("""
@@ -89,7 +89,6 @@ Please authenticate with GitHub:
         """)
         return False
 
-    print("✓ GitHub authentication verified")
     return True
 
 
@@ -107,5 +106,32 @@ def get_github_username() -> str | None:
     return result.stdout.strip()
 
 
+def get_current_user_id() -> int | None:
+    """
+    Get the GitHub user ID of the currently authenticated user.
+
+    Returns:
+        User ID or None if error
+    """
+    if not is_gh_authenticated():
+        return None
+
+    result = subprocess.run(
+        ["gh", "api", "user", "--jq", ".id"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"Error fetching user ID: {result.stderr}")
+        return None
+
+    try:
+        return int(result.stdout.strip())
+    except ValueError:
+        print("Error: Failed to parse user ID")
+        return None
+
+
 # TODO: use gh's token for pygithub to get repo issues
 # def get_repo_issues(owner: str, repo: str) -> list[dict]:

afterpython/tools/branch_rules.py

@@ -0,0 +1,106 @@
+"""
+Branch protection rules for AfterPython projects.
+Uses gh CLI to create GitHub rulesets.
+"""
+
+import json
+import subprocess
+from copy import deepcopy
+
+from afterpython.tools._git import is_gh_authenticated
+
+DEFAULT_RULESET = {
+    "name": "afterpython-default",  # The ruleset identifier in GitHub
+    "target": "branch",  # This ruleset applies to branches (not tags)
+    "enforcement": "active",  # Rules are enforced (vs "disabled" or "evaluate")
+    "conditions": {  # Which branches this ruleset applies to
+        "ref_name": {
+            "include": ["refs/heads/main"],  # Only protect the 'main' branch
+            "exclude": [],  # No exclusions
+        }
+    },
+    "bypass_actors": [
+        {
+            "actor_id": 5,  # Repository admin role
+            "actor_type": "RepositoryRole",
+            "bypass_mode": "always",
+        }
+    ],
+    "rules": [  # Array of protection rules
+        # Rule 1: No Force Pushes
+        {"type": "non_fast_forward"},  # Prevents git push --force
+        # Rule 2: No Branch Deletion
+        {"type": "deletion"},  # Prevents branch from being deleted
+        # Rule 3: CI Status Checks
+        {
+            "type": "required_status_checks",
+            "parameters": {
+                "required_status_checks": [
+                    {"context": "lint"},
+                    {"context": "test"},
+                    {"context": "build"},
+                ],
+                # The PR branch must be up to date with the base branch (main) before merging
+                "strict_required_status_checks_policy": True,
+            },
+        },
+    ],
+}
+
+
+def list_rulesets() -> list[dict] | None:
+    """
+    List existing rulesets for the current repository.
+
+    Returns:
+        List of rulesets or None if error
+    """
+    if not is_gh_authenticated():
+        return None
+
+    result = subprocess.run(
+        ["gh", "api", "repos/{owner}/{repo}/rulesets"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"Error listing rulesets: {result.stderr}")
+        return None
+
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print("Error: Failed to parse rulesets JSON")
+        return None
+
+
+def create_default_branch_rules(branch: str = "main") -> bool:
+    if not is_gh_authenticated():
+        return False
+
+    # Check if ruleset already exists
+    existing_rulesets = list_rulesets()
+    if existing_rulesets:
+        print(f"Ruleset '{DEFAULT_RULESET['name']}' already exists.")
+        return False
+
+    # Build payload
+    payload = deepcopy(DEFAULT_RULESET)
+    if branch != "main":
+        payload["conditions"]["ref_name"]["include"] = [f"refs/heads/{branch}"]
+
+    # Create ruleset
+    result = subprocess.run(
+        ["gh", "api", "-X", "POST", "repos/{owner}/{repo}/rulesets", "--input", "-"],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"Error creating ruleset: {result.stderr}")
+        return False
+
+    print(f"✓ Created branch ruleset '{DEFAULT_RULESET['name']}' for {branch=}")
+    return True

afterpython/tools/commitizen.py

@@ -1,6 +1,5 @@
 import afterpython as ap
 
-
 commitizen_default = {
     "tool": {
         "commitizen": {
@@ -36,8 +35,8 @@ commitizen_pre_commit_hook = {
 
 
 def init_commitizen():
-    from afterpython.tools.pre_commit import update_pre_commit
     from afterpython._io.toml import write_toml
+    from afterpython.tools.pre_commit import update_pre_commit
 
     afterpython_path = ap.paths.afterpython_path
     commitizen_toml_path = afterpython_path / "cz.toml"