sase-github 0.1.1__tar.gz → 0.1.3__tar.gz

sase_github-0.1.3/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.3"
+}

{sase_github-0.1.1 → sase_github-0.1.3}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.1.3](https://github.com/sase-org/sase-github/compare/v0.1.2...v0.1.3) (2026-06-29)
+
+
+### Features
+
+* write project display names for repo refs ([65ddc1d](https://github.com/sase-org/sase-github/commit/65ddc1d6dd9efe152897449ffa7eb421d8694802))
+
+
+### Documentation
+
+* add tiny field note ([d1d6563](https://github.com/sase-org/sase-github/commit/d1d6563822f3e48ec2504fed9156d1d0bbabb8a1))
+
+## [0.1.2](https://github.com/sase-org/sase-github/compare/v0.1.1...v0.1.2) (2026-06-13)
+
+
+### Bug Fixes
+
+* restore sase-github PyPI publish workflow ([077e91a](https://github.com/sase-org/sase-github/commit/077e91a57e836856d1e263cdc348cf3761516b4c))
+* use trusted publisher workflow path ([6a9fea0](https://github.com/sase-org/sase-github/commit/6a9fea00701428903f086ac871ac6c103521ae1d))
+
+
+### Documentation
+
+* add PyPI version badge ([58f0145](https://github.com/sase-org/sase-github/commit/58f014514664d6c8402b04bbaea37e0402099312))
+
 ## 0.1.1 (2026-06-09)
 
 

{sase_github-0.1.1 → sase_github-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sase-github
-Version: 0.1.1
+Version: 0.1.3
 Summary: GitHub VCS plugin for sase
 License-Expression: MIT
 License-File: LICENSE

{sase_github-0.1.1 → sase_github-0.1.3}/README.md

@@ -1,5 +1,6 @@
 # sase-github — GitHub VCS Plugin for sase
 
+[![PyPI](https://img.shields.io/pypi/v/sase-github?logo=pypi&logoColor=white)](https://pypi.org/project/sase-github/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![mypy](https://img.shields.io/badge/type_checker-mypy-blue.svg)](https://mypy-lang.org/)
 [![pytest](https://img.shields.io/badge/tests-pytest-blue.svg)](https://docs.pytest.org/)

sase_github-0.1.3/docs/architecture.md

@@ -0,0 +1,108 @@
+# Architecture
+
+sase-github is structured as two pluggy-based plugins that integrate with sase core via Python entry points.
+
+## Plugin System
+
+### Entry Points
+
+Registered in `pyproject.toml`:
+
+| Entry Point                 | Plugin                  | Purpose                                                         |
+| --------------------------- | ----------------------- | --------------------------------------------------------------- |
+| `sase_vcs:github`           | `GitHubPlugin`          | VCS operations (push, PR creation, PR info)                     |
+| `sase_workspace:github`     | `GitHubWorkspacePlugin` | Workspace orchestration (ref resolution, submission, mail prep) |
+| `sase_xprompts:sase_github` | —                       | Makes `#gh`, `#new_pr_desc`, `#prdd` xprompts discoverable      |
+| `sase_config:sase_github`   | —                       | Contributes `default_config.yml` to the sase config chain       |
+
+### GitHubPlugin (`plugin.py`)
+
+Extends `GitCommon` from sase core. Handles low-level VCS operations by wrapping `git` and `gh` CLI commands.
+
+**Hook implementations:**
+
+| Hook                        | Behavior                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------- |
+| `vcs_classify_repo()`       | Claims repos with `github.com` in their origin URL                                    |
+| `vcs_get_change_url()`      | Returns PR URL via `gh pr view --json url`                                            |
+| `vcs_get_cl_number()`       | Returns PR number via `gh pr view --json number`                                      |
+| `vcs_mail()`                | Pushes branch (`git push -u origin`) and creates PR if needed (`gh pr create --fill`) |
+| `vcs_create_pull_request()` | Creates a PR with an AI-generated title and body                                      |
+
+### GitHubWorkspacePlugin (`workspace_plugin.py`)
+
+Handles higher-level workflow orchestration. Implements workspace hooks for GitHub-hosted projects.
+
+**Hook implementations:**
+
+| Hook                                   | Behavior                                                                          |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| `ws_get_workflow_metadata()`           | Returns metadata for the `gh` workflow type (ref pattern `#gh`, vcs family `git`) |
+| `ws_detect_workflow_type()`            | Returns `"gh"` for repos with a remote origin URL (non-local)                     |
+| `ws_get_change_label()`                | Returns `"PR"` for GitHub projects                                                |
+| `ws_resolve_ref()`                     | Resolves `#gh` references (see [Reference Resolution](#reference-resolution))     |
+| `ws_extract_change_identifier()`       | Extracts PR number from GitHub PR URLs                                            |
+| `ws_generate_submitted_check_script()` | Generates a bash script that checks if a PR is merged via `gh pr view`            |
+| `ws_supports_reviewer_comments()`      | Returns `False` for GitHub URLs (critique comments not supported)                 |
+| `ws_get_workspace_directory()`         | Ensures git clone exists via `ensure_git_clone()`                                 |
+| `ws_prepare_mail()`                    | Displays branch/description and prompts user before pushing                       |
+| `ws_format_commit_description()`       | Prepends `[project]` prefix to commit messages                                    |
+| `ws_submit()`                          | Submits a ChangeSpec by merging its PR via `gh pr merge --merge --delete-branch`  |
+
+## Reference Resolution
+
+The `resolve_gh_ref()` function supports three dispatch modes for `#gh` references:
+
+### Mode 1: Repo Path (`user/project`)
+
+When the ref contains `/`, it's treated as a GitHub repo path:
+
+- Derives workspace from `~/projects/github/<user>/<project>/`
+- Clones the repo if it doesn't exist (SSH for orgs in `github_orgs`, HTTPS otherwise)
+- Reuses an existing SASE ProjectSpec whose normalized `WORKSPACE_DIR` already points at that workspace
+- Otherwise creates a canonical project name from the repo identity, normally `gh_<user>__<project>`
+- Adds a deterministic suffix such as `-2` only if that canonical project name is already occupied by a different
+  project, `PROJECT_NAME`, or alias
+- Sets `WORKSPACE_DIR` in the canonical project file
+- Sets a useful `PROJECT_NAME` for the repo basename, suffixing duplicate basenames as `<project>_1`, `<project>_2`, and
+  higher
+- Checks out the default branch
+
+This preserves legacy basename projects. If `~/.sase/projects/foo/foo.sase` already points at
+`~/projects/github/foo-org/foo/`, resolving `#gh:foo-org/foo` keeps using project `foo`; it does not rename or migrate
+the ProjectSpec. Existing auto-aliased GitHub projects are also left as-is and continue resolving through their alias.
+
+### Mode 2: Project Shorthand (`myproject`)
+
+When the ref matches an existing project directory, `PROJECT_NAME`, or project alias:
+
+- Resolves friendly names before project-directory lookup, so a generated `PROJECT_NAME` like `foo_1` points at its
+  canonical directory-key project
+- Looks up `~/.sase/projects/<name>/<name>.sase` (legacy `.gp` is read as a fallback)
+- Reads `WORKSPACE_DIR` from the project file
+- Checks out the default branch
+
+### Mode 3: ChangeSpec Name
+
+When the ref matches an existing ChangeSpec:
+
+- Searches all changespecs for a matching name
+- Reads `WORKSPACE_DIR` from the changespec's project file
+- Checks out `origin/<name>` (the ChangeSpec's branch)
+
+## Submission Flow
+
+When submitting a GitHub ChangeSpec (`ws_submit`):
+
+1. Kill and persist all running processes on the ChangeSpec
+2. Verify no active child ChangeSpecs exist
+3. Claim a workspace and checkout the ChangeSpec branch
+4. Check for an existing PR on the branch
+5. Merge via `gh pr merge --merge --delete-branch`
+6. Finalize submission (update ChangeSpec status)
+7. Release the workspace
+
+## Config Helper
+
+`config.py` provides `get_github_orgs()` which reads the `github_orgs` list from the merged sase config. This determines
+whether repos are cloned via SSH (for orgs the user has push access to) or HTTPS.

{sase_github-0.1.1 → sase_github-0.1.3}/docs/configuration.md

@@ -35,8 +35,8 @@ Currently the default config defines:
 ## Workspace Layout
 
 Primary GitHub workspaces are stored under `~/projects/github/<user>/<project>/` when first resolved from a
-`#gh(user/project)` reference. Numbered parallel-work checkouts follow SASE's shared `workspace.root` policy: by
-default they live under the platform state-root namespace, while explicit `workspace.root: adjacent` keeps the legacy
+`#gh(user/project)` reference. Numbered parallel-work checkouts follow SASE's shared `workspace.root` policy: by default
+they live under the platform state-root namespace, while explicit `workspace.root: adjacent` keeps the legacy
 `~/projects/github/<user>/<project>_<N>/` sibling layout.
 
 ## Project Files
@@ -47,9 +47,10 @@ when you first use an `#gh:<user>/<project>` ref.
 
 For new `owner/repo` refs, the project name is based on the full GitHub identity, normally `gh_<user>__<project>`, so
 two owners can have repositories with the same basename. If that canonical name is already occupied by a different
-project or alias, sase-github adds a deterministic suffix such as `-2`.
+project, `PROJECT_NAME`, or alias, sase-github adds a deterministic suffix such as `-2`.
 
-sase-github also writes a short `PROJECT_ALIASES` value for the repo basename when it is valid and useful. The first
-`owner/foo` repo can get alias `foo`; a second `owner/foo` repo gets the next available alias such as `foo-2`. Existing
+sase-github also writes `PROJECT_NAME` to the repo basename when it is valid and useful. The first `owner/foo` repo can
+get `PROJECT_NAME: foo`; a second `owner/foo` repo gets the next available display name such as `foo_1`. Existing
 basename ProjectSpecs are reused when their `WORKSPACE_DIR` already matches the GitHub workspace, so no automatic
-migration or rename is required. Inspect or adjust generated aliases with `sase project alias`.
+migration or rename is required. Existing auto-aliased GitHub projects are also left unchanged and keep resolving via
+their `PROJECT_ALIASES` entry.

{sase_github-0.1.1 → sase_github-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sase-github"
-version = "0.1.1"
+version = "0.1.3"
 description = "GitHub VCS plugin for sase"
 requires-python = ">=3.12"
 license = "MIT"

{sase_github-0.1.1 → sase_github-0.1.3}/src/sase_github/workspace_plugin.py

@@ -401,7 +401,7 @@ def _find_project_record_for_alias(
     alias: str,
 ) -> ProjectRecordWire | None:
     for record in records:
-        if alias in record.aliases:
+        if alias == getattr(record, "display_name", None) or alias in record.aliases:
             return record
     return None
 
@@ -422,10 +422,12 @@ def _canonical_project_name_base(user: str, project: str) -> str:
     return base
 
 
-def _project_name_or_aliases(records: Sequence[ProjectRecordWire]) -> set[str]:
+def _project_refs(records: Sequence[ProjectRecordWire]) -> set[str]:
     occupied: set[str] = set()
     for record in records:
         occupied.add(record.project_name)
+        if display_name := getattr(record, "display_name", None):
+            occupied.add(display_name)
         occupied.update(record.aliases)
     return occupied
 
@@ -436,7 +438,7 @@ def _allocate_canonical_project_name(
     records: Sequence[ProjectRecordWire],
 ) -> str:
     base = _canonical_project_name_base(user, project)
-    occupied = _project_name_or_aliases(records)
+    occupied = _project_refs(records)
 
     candidate = base
     suffix = 2
@@ -450,7 +452,7 @@ def _project_file_for(projects_base: Path, project_name: str) -> str:
     return preferred_project_spec_path(str(projects_base / project_name), project_name)
 
 
-def _ensure_useful_repo_alias(
+def _ensure_useful_repo_name(
     project_name: str,
     repo_name: str,
     *,
@@ -460,24 +462,24 @@ def _ensure_useful_repo_alias(
         return
 
     from sase.project_aliases import (
-        allocate_project_alias,
-        ensure_project_alias_locked,
+        allocate_project_name,
+        ensure_project_name_locked,
     )
 
     attempts = 3
     for attempt in range(attempts):
         records = _list_project_records(projects_base)
-        alias = allocate_project_alias(
+        display_name = allocate_project_name(
             repo_name,
             records,
             project_name=project_name,
         )
-        if alias == project_name:
+        if display_name == project_name:
             return
         try:
-            ensure_project_alias_locked(
+            ensure_project_name_locked(
                 project_name,
-                alias,
+                display_name,
                 projects_root=projects_base,
             )
             return
@@ -520,15 +522,15 @@ def _resolve_repo_path_ref(user: str, project: str) -> ResolvedRef:
         project_file = _project_file_for(projects_base, project_name)
         if not set_workspace_dir(project_file, primary_workspace_dir):
             raise ValueError(f"Failed to write WORKSPACE_DIR for '{project_name}'")
+        _ensure_useful_repo_name(
+            project_name,
+            project,
+            projects_base=projects_base,
+        )
     else:
         project_name = existing_record.project_name
         project_file = existing_record.project_file
 
-    _ensure_useful_repo_alias(
-        project_name,
-        project,
-        projects_base=projects_base,
-    )
     checkout_target = get_default_branch(primary_workspace_dir)
 
     return ResolvedRef(

{sase_github-0.1.1 → sase_github-0.1.3}/tests/test_workspace_plugin.py

@@ -38,7 +38,7 @@ class TestResolveGhRef:
     @patch(
         "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
     )
-    def test_repo_path_creates_canonical_project_and_alias(
+    def test_repo_path_creates_canonical_project_and_name(
         self, mock_branch: MagicMock
     ) -> None:
         with tempfile.TemporaryDirectory() as d:
@@ -61,12 +61,13 @@ class TestResolveGhRef:
             assert result.primary_workspace_dir == primary
             assert result.checkout_target == "origin/main"
             assert f"WORKSPACE_DIR: {primary}\n" in content
-            assert "PROJECT_ALIASES: myrepo\n" in content
+            assert "PROJECT_NAME: myrepo\n" in content
+            assert "PROJECT_ALIASES" not in content
 
     @patch(
         "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
     )
-    def test_duplicate_repo_basename_gets_distinct_alias(
+    def test_duplicate_repo_basename_gets_distinct_name(
         self, mock_branch: MagicMock
     ) -> None:
         with tempfile.TemporaryDirectory() as d:
@@ -82,8 +83,8 @@ class TestResolveGhRef:
             second_file = Path(second.project_file)
             assert first.project_name == "gh_foo-org__foo"
             assert second.project_name == "gh_bar-org__foo"
-            assert "PROJECT_ALIASES: foo\n" in first_file.read_text(encoding="utf-8")
-            assert "PROJECT_ALIASES: foo-2\n" in second_file.read_text(encoding="utf-8")
+            assert "PROJECT_NAME: foo\n" in first_file.read_text(encoding="utf-8")
+            assert "PROJECT_NAME: foo_1\n" in second_file.read_text(encoding="utf-8")
 
     @patch(
         "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
@@ -108,6 +109,30 @@ class TestResolveGhRef:
             assert result.project_file == str(project_file)
             assert "PROJECT_ALIASES" not in content
 
+    @patch(
+        "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
+    )
+    def test_repo_path_reuses_existing_auto_aliased_project_without_migration(
+        self, mock_branch: MagicMock
+    ) -> None:
+        with tempfile.TemporaryDirectory() as d:
+            home = Path(d)
+            primary = _github_workspace(home, "alice", "myrepo")
+            project_file = _write_project(
+                home,
+                "gh_alice__myrepo",
+                f"WORKSPACE_DIR: {primary}\nPROJECT_ALIASES: myrepo\nNAME: legacy\n",
+            )
+            path_patch, env_patch = _home_patches(home)
+            with path_patch, env_patch:
+                result = resolve_gh_ref("alice/myrepo")
+
+            content = project_file.read_text(encoding="utf-8")
+            assert result.project_name == "gh_alice__myrepo"
+            assert result.project_file == str(project_file)
+            assert "PROJECT_ALIASES: myrepo\n" in content
+            assert "PROJECT_NAME" not in content
+
     @patch(
         "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
     )
@@ -129,7 +154,8 @@ class TestResolveGhRef:
             content = Path(result.project_file).read_text(encoding="utf-8")
             assert result.project_name == "gh_alice__foo"
             assert result.primary_workspace_dir == primary
-            assert "PROJECT_ALIASES: foo-2\n" in content
+            assert "PROJECT_NAME: foo_1\n" in content
+            assert "PROJECT_ALIASES" not in content
 
     @patch(
         "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
@@ -150,14 +176,14 @@ class TestResolveGhRef:
                 result = resolve_gh_ref("alice/foo")
 
             assert result.project_name == "gh_alice__foo-2"
-            assert "PROJECT_ALIASES: foo\n" in Path(result.project_file).read_text(
+            assert "PROJECT_NAME: foo\n" in Path(result.project_file).read_text(
                 encoding="utf-8"
             )
 
     @patch(
         "sase_github.workspace_plugin.get_default_branch", return_value="origin/main"
     )
-    def test_project_alias_shorthand_resolves_canonical_project(
+    def test_project_name_shorthand_resolves_canonical_project(
         self, mock_branch: MagicMock
     ) -> None:
         with tempfile.TemporaryDirectory() as d:
@@ -168,7 +194,7 @@ class TestResolveGhRef:
             with path_patch, env_patch:
                 resolve_gh_ref("foo-org/foo")
                 canonical = resolve_gh_ref("bar-org/foo")
-                alias = resolve_gh_ref("foo-2")
+                alias = resolve_gh_ref("foo_1")
 
             assert alias.project_name == canonical.project_name
             assert alias.project_file == canonical.project_file

sase_github-0.1.1/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.1.1"
-}

sase_github-0.1.1/docs/architecture.md

@@ -1,105 +0,0 @@
-# Architecture
-
-sase-github is structured as two pluggy-based plugins that integrate with sase core via Python entry points.
-
-## Plugin System
-
-### Entry Points
-
-Registered in `pyproject.toml`:
-
-| Entry Point | Plugin | Purpose |
-|---|---|---|
-| `sase_vcs:github` | `GitHubPlugin` | VCS operations (push, PR creation, PR info) |
-| `sase_workspace:github` | `GitHubWorkspacePlugin` | Workspace orchestration (ref resolution, submission, mail prep) |
-| `sase_xprompts:sase_github` | — | Makes `#gh`, `#new_pr_desc`, `#prdd` xprompts discoverable |
-| `sase_config:sase_github` | — | Contributes `default_config.yml` to the sase config chain |
-
-### GitHubPlugin (`plugin.py`)
-
-Extends `GitCommon` from sase core. Handles low-level VCS operations by wrapping `git` and `gh` CLI commands.
-
-**Hook implementations:**
-
-| Hook | Behavior |
-|---|---|
-| `vcs_classify_repo()` | Claims repos with `github.com` in their origin URL |
-| `vcs_get_change_url()` | Returns PR URL via `gh pr view --json url` |
-| `vcs_get_cl_number()` | Returns PR number via `gh pr view --json number` |
-| `vcs_mail()` | Pushes branch (`git push -u origin`) and creates PR if needed (`gh pr create --fill`) |
-| `vcs_create_pull_request()` | Creates a PR with an AI-generated title and body |
-
-### GitHubWorkspacePlugin (`workspace_plugin.py`)
-
-Handles higher-level workflow orchestration. Implements workspace hooks for GitHub-hosted projects.
-
-**Hook implementations:**
-
-| Hook | Behavior |
-|---|---|
-| `ws_get_workflow_metadata()` | Returns metadata for the `gh` workflow type (ref pattern `#gh`, vcs family `git`) |
-| `ws_detect_workflow_type()` | Returns `"gh"` for repos with a remote origin URL (non-local) |
-| `ws_get_change_label()` | Returns `"PR"` for GitHub projects |
-| `ws_resolve_ref()` | Resolves `#gh` references (see [Reference Resolution](#reference-resolution)) |
-| `ws_extract_change_identifier()` | Extracts PR number from GitHub PR URLs |
-| `ws_generate_submitted_check_script()` | Generates a bash script that checks if a PR is merged via `gh pr view` |
-| `ws_supports_reviewer_comments()` | Returns `False` for GitHub URLs (critique comments not supported) |
-| `ws_get_workspace_directory()` | Ensures git clone exists via `ensure_git_clone()` |
-| `ws_prepare_mail()` | Displays branch/description and prompts user before pushing |
-| `ws_format_commit_description()` | Prepends `[project]` prefix to commit messages |
-| `ws_submit()` | Submits a ChangeSpec by merging its PR via `gh pr merge --merge --delete-branch` |
-
-## Reference Resolution
-
-The `resolve_gh_ref()` function supports three dispatch modes for `#gh` references:
-
-### Mode 1: Repo Path (`user/project`)
-
-When the ref contains `/`, it's treated as a GitHub repo path:
-
-- Derives workspace from `~/projects/github/<user>/<project>/`
-- Clones the repo if it doesn't exist (SSH for orgs in `github_orgs`, HTTPS otherwise)
-- Reuses an existing SASE ProjectSpec whose normalized `WORKSPACE_DIR` already points at that workspace
-- Otherwise creates a canonical project name from the repo identity, normally `gh_<user>__<project>`
-- Adds a deterministic suffix such as `-2` only if that canonical project name is already occupied by a different
-  project or alias
-- Sets `WORKSPACE_DIR` in the canonical project file
-- Ensures a useful short alias for the repo basename, suffixing duplicate basenames as `<project>-2`, `<project>-3`,
-  and higher
-- Checks out the default branch
-
-This preserves legacy basename projects. If `~/.sase/projects/foo/foo.sase` already points at
-`~/projects/github/foo-org/foo/`, resolving `#gh:foo-org/foo` keeps using project `foo`; it does not rename or migrate
-the ProjectSpec.
-
-### Mode 2: Project Shorthand (`myproject`)
-
-When the ref matches an existing project directory or project alias:
-
-- Resolves aliases before project-directory lookup, so a generated alias like `foo-2` points at its canonical project
-- Looks up `~/.sase/projects/<name>/<name>.sase` (legacy `.gp` is read as a fallback)
-- Reads `WORKSPACE_DIR` from the project file
-- Checks out the default branch
-
-### Mode 3: ChangeSpec Name
-
-When the ref matches an existing ChangeSpec:
-- Searches all changespecs for a matching name
-- Reads `WORKSPACE_DIR` from the changespec's project file
-- Checks out `origin/<name>` (the ChangeSpec's branch)
-
-## Submission Flow
-
-When submitting a GitHub ChangeSpec (`ws_submit`):
-
-1. Kill and persist all running processes on the ChangeSpec
-2. Verify no active child ChangeSpecs exist
-3. Claim a workspace and checkout the ChangeSpec branch
-4. Check for an existing PR on the branch
-5. Merge via `gh pr merge --merge --delete-branch`
-6. Finalize submission (update ChangeSpec status)
-7. Release the workspace
-
-## Config Helper
-
-`config.py` provides `get_github_orgs()` which reads the `github_orgs` list from the merged sase config. This determines whether repos are cloned via SSH (for orgs the user has push access to) or HTTPS.