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

{sase_github-0.1.0 → sase_github-0.1.1}/.github/workflows/ci.yml

@@ -2,18 +2,28 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [master]
   pull_request:
-    branches: [main]
+    branches: [master]
 
 permissions:
   contents: read
 
+env:
+  SASE_CORE_REF: v0.1.3
+  SASE_CORE_PATH: .ci/sase
+
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Check out SASE
+        uses: actions/checkout@v4
+        with:
+          repository: sase-org/sase
+          ref: ${{ env.SASE_CORE_REF }}
+          path: ${{ env.SASE_CORE_PATH }}
       - uses: astral-sh/setup-uv@v4
         with:
           enable-cache: true
@@ -33,6 +43,12 @@ jobs:
         python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
+      - name: Check out SASE
+        uses: actions/checkout@v4
+        with:
+          repository: sase-org/sase
+          ref: ${{ env.SASE_CORE_REF }}
+          path: ${{ env.SASE_CORE_PATH }}
       - uses: astral-sh/setup-uv@v4
         with:
           enable-cache: true

sase_github-0.1.1/.github/workflows/pr-title.yml

@@ -0,0 +1,31 @@
+name: PR Title
+
+on:
+  pull_request:
+    branches: [master]
+    types: [opened, edited, reopened, ready_for_review, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  conventional-title:
+    name: Conventional PR title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate squash-merge title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+
+          allowed_types='feat|fix|perf|docs|ci|test|chore|refactor|build|deps'
+          pattern="^(${allowed_types})(\([A-Za-z0-9._/-]+\))?!?: [^[:space:]].*"
+
+          if [[ ! "${PR_TITLE}" =~ ${pattern} ]]; then
+            printf 'PR title must follow Conventional Commits so squash merges produce useful release metadata.\n' >&2
+            printf 'Allowed types: feat, fix, perf, docs, ci, test, chore, refactor, build, deps.\n' >&2
+            printf 'Examples: fix(release): add release workflow, feat!: remove legacy config.\n' >&2
+            printf 'Actual title: %s\n' "${PR_TITLE}" >&2
+            exit 1
+          fi

sase_github-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,125 @@
+name: Publish
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+    inputs:
+      publish_existing:
+        description: Publish the existing release artifacts for the version on master
+        required: true
+        type: boolean
+        default: false
+
+env:
+  SASE_CORE_REF: v0.1.3
+  SASE_CORE_PATH: .ci/sase
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created || 'false' }}
+    steps:
+      - uses: googleapis/release-please-action@v5
+        if: ${{ github.event_name == 'push' }}
+        id: release
+        with:
+          token: ${{ secrets.SASE_RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build:
+    needs: release
+    if: ${{ needs.release.outputs.release_created == 'true' || (github.event_name == 'workflow_dispatch' && inputs.publish_existing == true) }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Build package
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  install-smoke:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Check out SASE
+        uses: actions/checkout@v4
+        with:
+          repository: sase-org/sase
+          ref: ${{ env.SASE_CORE_REF }}
+          path: ${{ env.SASE_CORE_PATH }}
+      - uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install built sase-github wheel into a fresh venv
+        run: |
+          uv venv --python 3.12 /tmp/smoke-venv
+          uv pip install --python /tmp/smoke-venv/bin/python "${SASE_CORE_PATH}"
+          uv pip install --python /tmp/smoke-venv/bin/python dist/*.whl
+      - name: Smoke check
+        run: |
+          /tmp/smoke-venv/bin/python - <<'PY'
+          from importlib.metadata import entry_points
+
+          import sase_github
+
+          expected = {
+              "sase_vcs": {"github": "sase_github.plugin:GitHubPlugin"},
+              "sase_workspace": {
+                  "github": "sase_github.workspace_plugin:GitHubWorkspacePlugin"
+              },
+              "sase_config": {"sase_github": "sase_github"},
+              "sase_xprompts": {"sase_github": "sase_github"},
+          }
+
+          discovered = entry_points()
+          for group, entries in expected.items():
+              group_entries = {
+                  entry_point.name: entry_point.value
+                  for entry_point in discovered.select(group=group)
+              }
+              for name, value in entries.items():
+                  actual = group_entries.get(name)
+                  if actual != value:
+                      raise SystemExit(
+                          f"{group} entry point {name!r}: expected {value!r}, got {actual!r}"
+                      )
+
+          assert sase_github
+          PY
+
+  publish:
+    needs: [release, build, install-smoke]
+    if: ${{ needs.release.outputs.release_created == 'true' || (github.event_name == 'workflow_dispatch' && inputs.publish_existing == true) }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

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

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

sase_github-0.1.1/.sase_beads/config.json

@@ -0,0 +1,5 @@
+{
+  "issue_prefix": "sase-github",
+  "next_counter": 1,
+  "owner": "bryanbugyi34@gmail.com"
+}

sase_github-0.1.1/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 0.1.1 (2026-06-09)
+
+
+### Features
+
+* Add #prdd xprompt tagged with append_to_commit_and_propose ([cc29edd](https://github.com/sase-org/sase-github/commit/cc29eddaaad0e9dbdef90e045dc8e3bb046e7dbd))
+* Add can_rename_branch override returning False ([f60d739](https://github.com/sase-org/sase-github/commit/f60d739b5278a625c39972aab748b736775a6d20))
+* Add default_config.yml with pr_diff xprompt and sase_config entry point ([d1e9592](https://github.com/sase-org/sase-github/commit/d1e9592fb5f81954335b90d7747931c262f440cb))
+* add descriptions to GitHub xprompts (sase-3w.5) ([ceb2c51](https://github.com/sase-org/sase-github/commit/ceb2c51bdd491a09c4128507fb6e6ee5e2772375))
+* Add finally: true to release and diff steps in gh workflow ([3b7786e](https://github.com/sase-org/sase-github/commit/3b7786e734f9b256f745435daf78b29f297eb9a4))
+* Add GitHubWorkspacePlugin and migrate scripts from sase core ([b6e1499](https://github.com/sase-org/sase-github/commit/b6e1499de165a6d0b22bbb39207e4ae913ee7954))
+* Add LLM provider model name and agent name to PR description ([8a22569](https://github.com/sase-org/sase-github/commit/8a225697ba94bc23e6b78361d8ce371d693899e5))
+* Add post-cleanup git pull to #gh xprompt workflow ([96bdc31](https://github.com/sase-org/sase-github/commit/96bdc31ad241f8a505055b3a8e2fc524cffb265d))
+* Add rollover tag to gh VCS xprompt workflow ([661200c](https://github.com/sase-org/sase-github/commit/661200c32b0a9d724d98d006b36d88518c71b4e0))
+* Add VCS check hooks for GitHub workspace plugin ([cd43132](https://github.com/sase-org/sase-github/commit/cd43132898038b96150a68b2216d30afcae8a696))
+* Add VCS commit dispatch hooks (vcs_create_commit, vcs_create_proposal, vcs_create_pull_request) with tests (sase-a.1) ([1147d77](https://github.com/sase-org/sase-github/commit/1147d77ad77113c85feba7be3d17a0aa0fca3b10))
+* Add vcs_classify_repo hook to claim repos with github.com URLs ([5098353](https://github.com/sase-org/sase-github/commit/50983531c226fb7d6977b5b1fe526cba11b8f473))
+* Add vcs_get_change_body hook implementation ([d264a57](https://github.com/sase-org/sase-github/commit/d264a572657cd2a95e2858bf1872f13b1894377d))
+* Add workflow_label to #gh xprompt for descriptive RUNNING field names ([3020428](https://github.com/sase-org/sase-github/commit/3020428201e0714052f9ac51e3b5e2972b2bd102))
+* Add wraps_all flag to gh xprompt (sase-4.2) ([fd56d9c](https://github.com/sase-org/sase-github/commit/fd56d9cf7114fb763e07d8b05a8172b9ee355ef2))
+* Add ws_prepare_mail hookimpl for GitHub git mail prep ([8865801](https://github.com/sase-org/sase-github/commit/886580159a80c5fba6a285975459547e6987b52d))
+* allocate GitHub project aliases on first use (sase-4d.2) ([3fa99c8](https://github.com/sase-org/sase-github/commit/3fa99c8cc44825581c3ecd8a281402d2d9a087e2))
+* Allow slash as VCS ref separator in #gh pattern ([e126779](https://github.com/sase-org/sase-github/commit/e126779256305df3e22cef8fb804f22899aa8111))
+* Allow underscore as VCS ref separator (#gh_sase = #gh:sase) ([46aaabf](https://github.com/sase-org/sase-github/commit/46aaabf7ccfb7a75c085cc3ef4a381a97c09e487))
+* Create %gh runner provider (%w:sase-yyyx.4) ([db2878d](https://github.com/sase-org/sase-github/commit/db2878d7af28c9b80d25c796fd5986cd3d079566))
+* Data-Driven VCS Family Mapping + running_field.py Cleanup ([7128545](https://github.com/sase-org/sase-github/commit/7128545b5f681efb31b3df6f2828d900d4ac0190))
+* Fix #pr branch naming and #gh checkout for project names ([f2c84dc](https://github.com/sase-org/sase-github/commit/f2c84dcb9b526e477f187869de8e481af7c65370))
+* Implement vcs_abandon_change hook to close PRs during revert/archive (sase-c.2) ([94f3902](https://github.com/sase-org/sase-github/commit/94f3902b3432ff0d308ea076399ea520cffbbc9a))
+* Implement ws_get_workflow_metadata hook for GitHub plugin ([39d6513](https://github.com/sase-org/sase-github/commit/39d65139c107fd7205232d20a765608f7e5de1ed))
+* Implement ws_get_workspace_directory and ws_format_commit_description hooks ([393e77d](https://github.com/sase-org/sase-github/commit/393e77d21eaa4b1f1402a6d6a77e89697dfb3cd1))
+* Inherit some VCS hooks from the common git impl ([879cd47](https://github.com/sase-org/sase-github/commit/879cd475549281c5a3c667d27de0a284ced9531f))
+* Initial sase-github plugin package ([5372725](https://github.com/sase-org/sase-github/commit/537272566798840ec725169ecf676838b630854e))
+* Make #pr fail fast when not on right branch ([eb475ba](https://github.com/sase-org/sase-github/commit/eb475baf24a86a522ded541f8911519a6f6a6dc6))
+* prefer .sase project spec extension with legacy .gp fallback (sase-33.5a) (sase-33) ([9340d36](https://github.com/sase-org/sase-github/commit/9340d3676f0c15bd6b67dfa8d4b9da2372523e7a))
+* Replace github_username with github_orgs list config ([11420cf](https://github.com/sase-org/sase-github/commit/11420cfbdc1b0c65601c11a6ca77b9eba3f05b3c))
+* Skip prdd xprompt expansion on default branch ([add1609](https://github.com/sase-org/sase-github/commit/add160966c8803a8af6c278f701fa53a6d1d329b))
+* Support use_project_pr_prefix config for PR title prefixing ([21a76b7](https://github.com/sase-org/sase-github/commit/21a76b7d2fe04c5bef523dd585062ad459d89619))
+* Use _pr_body payload field for PR description body ([e3f48c7](https://github.com/sase-org/sase-github/commit/e3f48c75ed3dbf133f588ba763491a1e50ee7972))
+* Use commit message body as PR description when available ([ecabacd](https://github.com/sase-org/sase-github/commit/ecabacd1ae5797475379fa21b2e41b60658054ab))
+
+
+### Bug Fixes
+
+* #pr_diff showing unrelated file changes ([1c7cc23](https://github.com/sase-org/sase-github/commit/1c7cc23b9c219102fde9e30d867f0113a13c6708))
+* Add explicit git push and robust URL extraction to #pr workflow ([b4da722](https://github.com/sase-org/sase-github/commit/b4da7226372b0722b93b0faf57eaa717bb5308c1))
+* Add vcs_provider_name='github' to workspace plugin metadata ([05f5f1e](https://github.com/sase-org/sase-github/commit/05f5f1e18e64232c69ab4f87ed7ea130b80d3729))
+* Checkout CL branch in #gh workflow before agent runs ([32163e0](https://github.com/sase-org/sase-github/commit/32163e0298a83e424b3ceb6e07aa933a0281e4ba))
+* Emit meta_new_pr output so PR URL appears in ace TUI metadata panel ([83de875](https://github.com/sase-org/sase-github/commit/83de8753bbf3557b8c647fcbcdb69196dacff056))
+* Fix PR description footer newline between Model and Agent lines ([087f9fd](https://github.com/sase-org/sase-github/commit/087f9fdd53356d22e1a011b3307229b5733510b0))
+* Handle existing branch in #pr workflow create_branch step ([d5a212a](https://github.com/sase-org/sase-github/commit/d5a212a469a61ad7bbbd02f8681501ced90cbc50))
+* Handle remote branch already existing in pr create_branch step ([b3a8196](https://github.com/sase-org/sase-github/commit/b3a81964c39b2e4c20a8aa87c6d28aec04f641c3))
+* Inline pr_diff logic into prdd.yml so #pr_diff expands correctly ([28c428c](https://github.com/sase-org/sase-github/commit/28c428c3445a962d6682b1cd2fc652542896cae3))
+* Make #prdd not show when not in a git repo ([8742394](https://github.com/sase-org/sase-github/commit/87423942a35fd90599c7f8908717e83c5b42bca4))
+* Remove pipefail from #pr create_branch step (incompatible with dash) ([fceee3e](https://github.com/sase-org/sase-github/commit/fceee3e8ae7441c30a6dd756783ac63a286e0e55))
+* Stash and pull as pre-step ([bbd8488](https://github.com/sase-org/sase-github/commit/bbd8488648d213059b88d0d9a1f2b50f7b656565))
+* update callers for removed ensure_git_clone wrapper ([8a21fc2](https://github.com/sase-org/sase-github/commit/8a21fc2e63a4b8306552f1059746ac814d7864b3))
+* Update stale test mocks for commit, proposal, and PR tests ([2bee80d](https://github.com/sase-org/sase-github/commit/2bee80d81bb37bb2fa9322d90684d9b2ceda073a))
+* Update test to match new branch-reuse behavior in #pr workflow ([1ef7569](https://github.com/sase-org/sase-github/commit/1ef7569ce56833c8bb4b482b78dd21108442fb15))
+* Use comma separator for multi-value xprompt tags in gh.yml ([1204d2b](https://github.com/sase-org/sase-github/commit/1204d2b95ab3ea302e5f5687eff2296dd0c2d47f))
+* Use parent PID in gh_setup to prevent stale RUNNING entry cleanup ([09d0703](https://github.com/sase-org/sase-github/commit/09d07039ed59028d1dc4230b582bbb5ae21c2bfd))
+* Use recorded PR URL for submit instead of branch heuristics ([e0f5013](https://github.com/sase-org/sase-github/commit/e0f5013636df527f9607bd6a269df606f8319788))

{sase_github-0.1.0 → sase_github-0.1.1}/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Overview
 GitHub VCS plugin for sase. Provides GitHubPlugin (PR creation, gh CLI integration)
-and GitHub-related xprompts (#gh, #pr, #new_pr_desc).
+and GitHub-related xprompts (#gh, #new_pr_desc).
 
 ## Build & Run
 ```bash
@@ -16,7 +16,7 @@ just check      # lint + test
 ## Architecture
 - `src/sase_github/plugin.py` — GitHubPlugin class (extends `sase.vcs_provider.plugins._git_common.GitCommon`)
 - `src/sase_github/xprompts/` — GitHub workflow YAML files discovered via `sase_xprompts` entry point
-- Depends on `sase>=0.1.0` for base classes, hookspec, and script modules
+- Depends on `sase>=0.1.3` for base classes, hookspec, and script modules
 
 ## Code Conventions
 - Absolute imports: `from sase_github.plugin import GitHubPlugin`

{sase_github-0.1.0 → sase_github-0.1.1}/Justfile

@@ -7,9 +7,13 @@ default:
     @just --list
 
 _setup:
-    @[ -x {{ venv_bin }}/python ] || (uv venv {{ venv_dir }} && uv pip install -e ".[dev]")
+    @[ -x {{ venv_bin }}/python ] || (uv venv {{ venv_dir }} && just install)
 
-install: _setup
+install:
+    @[ -x {{ venv_bin }}/python ] || uv venv {{ venv_dir }}
+    @if [ -n "${SASE_CORE_PATH:-}" ]; then \
+        uv pip install -e "${SASE_CORE_PATH}"; \
+    fi
     uv pip install -e ".[dev]"
 
 lint: _setup

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: sase-github
-Version: 0.1.0
+Version: 0.1.1
 Summary: GitHub VCS plugin for sase
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: sase>=0.1.0
+Requires-Dist: sase>=0.1.3
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'

sase_github-0.1.1/README.md

@@ -0,0 +1,107 @@
+# sase-github — GitHub VCS Plugin for sase
+
+[![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/)
+
+## Overview
+
+**sase-github** is a plugin for [sase](https://github.com/sase-org/sase) that adds GitHub-specific VCS and workspace
+support. It provides the `GitHubPlugin` VCS provider and `GitHubWorkspacePlugin` workspace provider for GitHub-hosted
+repositories, integrating with the `gh` CLI for pull request creation, management, and submission, along with
+GitHub-specific xprompt workflows.
+
+## Installation
+
+```bash
+pip install sase-github
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install sase-github
+```
+
+Requires `sase>=0.1.3` as a dependency (installed automatically).
+
+## What's Included
+
+### VCS Provider
+
+- **GitHubPlugin** — GitHub VCS provider that extends `GitCommon` with `gh` CLI integration for PR workflows (push,
+  create PR, retrieve PR URL/number)
+
+### Workspace Provider
+
+- **GitHubWorkspacePlugin** — Workspace provider that handles GitHub-specific workflow orchestration: reference
+  resolution (repo paths, project names, changespec names), PR submission via `gh pr merge`, branch management, and
+  commit description formatting
+
+### Configuration
+
+- **`get_github_orgs()`** — Reads `github_orgs` from sase config to determine SSH vs HTTPS clone URLs for
+  organizations/users with push access
+
+### XPrompts
+
+| XPrompt        | Description                                                                        |
+| -------------- | ---------------------------------------------------------------------------------- |
+| `#gh`          | GitHub workflow orchestration — resolves refs, claims workspaces, manages branches |
+| `#new_pr_desc` | AI-generated PR descriptions from commit diffs                                     |
+| `#prdd`        | Injects PR diff and description as context (auto-appended on feature branches)     |
+
+## How It Works
+
+sase-github uses Python [entry points](https://packaging.python.org/en/latest/specifications/entry-points/) to register
+itself with sase core:
+
+- **`sase_vcs`** — Registers `GitHubPlugin` as the `github` VCS provider
+- **`sase_workspace`** — Registers `GitHubWorkspacePlugin` as the `github` workspace provider
+- **`sase_xprompts`** — Makes GitHub xprompts discoverable via plugin discovery
+
+When sase detects a GitHub-hosted repository (via `gh` CLI), it automatically loads `GitHubPlugin` and
+`GitHubWorkspacePlugin` to handle VCS operations like PR creation, branch management, commit workflows, and PR
+submission.
+
+## Requirements
+
+- Python 3.12+
+- [sase](https://github.com/sase-org/sase) >= 0.1.3
+- [gh](https://cli.github.com/) CLI (for GitHub API operations)
+
+## Development
+
+```bash
+just install    # Install in editable mode with dev deps
+just fmt        # Auto-format code
+just lint       # Run ruff + mypy
+just test       # Run tests
+just check      # All checks (lint + test)
+just build      # Build distribution packages
+just clean      # Remove build artifacts
+```
+
+Set `SASE_CORE_PATH=/path/to/sase` when you need development installs to use an editable SASE checkout before installing
+`sase-github`.
+
+## Project Structure
+
+```
+src/sase_github/
+├── __init__.py              # Package exports
+├── plugin.py                # GitHubPlugin VCS implementation
+├── workspace_plugin.py      # GitHubWorkspacePlugin workspace implementation
+├── config.py                # GitHub config helpers (org/user list)
+├── scripts/
+│   ├── gh_setup.py                 # Setup step for #gh workflow
+│   └── new_pr_desc_get_context.py  # Context retrieval for PR description generation
+└── xprompts/
+    ├── gh.yml              # GitHub workflow orchestration
+    ├── new_pr_desc.yml     # PR description generation
+    └── prdd.yml            # PR description detail injection
+```
+
+## License
+
+MIT

sase_github-0.1.1/docs/architecture.md

@@ -0,0 +1,105 @@
+# 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.

sase_github-0.1.1/docs/configuration.md

@@ -0,0 +1,55 @@
+# Configuration
+
+## `github_orgs`
+
+The `github_orgs` setting controls how sase-github clones repositories. Add it to your sase config file
+(`~/.config/sase/sase.yml`):
+
+```yaml
+github_orgs:
+  - your-username
+  - your-org
+```
+
+**Effect:** When cloning a repo whose owner is in this list, sase-github uses SSH (`git@github.com:user/project.git`).
+For all other repos, it uses HTTPS (`https://github.com/user/project.git`).
+
+This matters because SSH URLs require an SSH key configured with GitHub, while HTTPS URLs work for public repos without
+authentication (but require a token for push access).
+
+## Default Config
+
+sase-github contributes a `default_config.yml` via the `sase_config` entry point. This is merged into the sase config
+chain between sase core defaults and your user config.
+
+Currently the default config defines:
+
+- `xprompts.pr_diff` — an xprompt that expands to the diff of the current PR's changes
+
+## Requirements
+
+- **`gh` CLI** — Required for all PR operations. Install from https://cli.github.com/ and authenticate with
+  `gh auth login`.
+- **Git** — Standard git CLI for repository operations.
+
+## 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
+`~/projects/github/<user>/<project>_<N>/` sibling layout.
+
+## Project Files
+
+Project metadata is stored in `~/.sase/projects/<project>/<project>.sase`; legacy `.gp` files remain readable as a
+fallback. The key field is `WORKSPACE_DIR`, which points to the primary workspace directory and is set automatically
+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`.
+
+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
+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`.