afwf_github 1.0.1__tar.gz

afwf_github-1.0.1/AUTHORS.rst

@@ -0,0 +1,15 @@
+.. _about_author:
+
+About the Author
+------------------------------------------------------------------------------
+::
+
+   (\ (\
+   ( -.-)o
+   o_(")(")
+
+**Sanhe Hu** is a seasoned software engineer with a deep passion for Python development since 2010. As an author and maintainer of `150+ open-source Python projects <https://pypi.org/user/machugwu/>`_, with over `15 million monthly downloads <https://github.com/MacHu-GWU>`_, I bring a wealth of experience to the table. As a Senior Solution Architect and Subject Matter Expert in AI, Data, Amazon Web Services, Cloud Engineering, DevOps, I thrive on helping clients with platform design, enterprise architecture, and strategic roadmaps.
+
+Talk is cheap, show me the code:
+
+- My Github: https://github.com/MacHu-GWU

afwf_github-1.0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanhe Hu <husanhe@email.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

afwf_github-1.0.1/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: afwf_github
+Version: 1.0.1
+Summary: Alfred GitHub Workflow.
+Author-email: Sanhe Hu <husanhe@email.com>
+Maintainer-email: Sanhe Hu <husanhe@email.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MacHu-GWU/afwf_github-project
+Project-URL: Documentation, https://afwf-github.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/MacHu-GWU/afwf_github-project
+Project-URL: Issues, https://github.com/MacHu-GWU/afwf_github-project/issues
+Project-URL: Changelog, https://github.com/MacHu-GWU/afwf_github-project/blob/main/release-history.rst
+Project-URL: Download, https://pypi.org/pypi/afwf-github#files
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+License-File: AUTHORS.rst
+Requires-Dist: pydantic<3.0.0,>=2.11.10
+Requires-Dist: afwf<2.0.0,>=1.0.2
+Requires-Dist: diskcache<6.0.0,>=5.6.3
+Requires-Dist: PyGithub<3.0.0,>=2.8.1
+Requires-Dist: git-web-url<2.0.0,>=1.0.2
+Requires-Dist: sayt2<1.0.0,>=0.1.2
+Requires-Dist: home-secret-toml<1.0.0,>=0.2.1
+Requires-Dist: fire<1.0.0,>=0.6.0
+Provides-Extra: dev
+Requires-Dist: rich<15.0.0,>=13.8.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest<9.0.0,>=8.2.2; extra == "test"
+Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "test"
+Provides-Extra: doc
+Requires-Dist: Sphinx<8.0.0,>=7.4.7; extra == "doc"
+Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
+Requires-Dist: sphinx-design<1.0.0,>=0.6.1; extra == "doc"
+Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
+Requires-Dist: furo==2024.8.6; extra == "doc"
+Requires-Dist: pygments<3.0.0,>=2.18.0; extra == "doc"
+Requires-Dist: ipython<8.19.0,>=8.18.1; extra == "doc"
+Requires-Dist: nbsphinx<1.0.0,>=0.8.12; extra == "doc"
+Requires-Dist: rstobj==2.0.0; extra == "doc"
+Requires-Dist: docfly==3.0.3; extra == "doc"
+Provides-Extra: mise
+Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
+Requires-Dist: httpx<1.0.0,>=0.28.0; extra == "mise"
+Requires-Dist: tomli<3.0.0,>=2.0.0; python_version < "3.11" and extra == "mise"
+Dynamic: license-file
+
+
+.. image:: https://readthedocs.org/projects/afwf-github/badge/?version=latest
+    :target: https://afwf-github.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://github.com/MacHu-GWU/afwf_github-project/actions/workflows/main.yml/badge.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/actions?query=workflow:CI
+
+.. image:: https://codecov.io/gh/MacHu-GWU/afwf_github-project/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/MacHu-GWU/afwf_github-project
+
+.. image:: https://img.shields.io/pypi/v/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/pypi/l/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/pypi/pyversions/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/afwf_github-project/blob/main/release-history.rst
+
+.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/afwf_github-project
+
+------
+
+.. image:: https://img.shields.io/badge/Link-API-blue.svg
+    :target: https://afwf-github.readthedocs.io/en/latest/py-modindex.html
+
+.. image:: https://img.shields.io/badge/Link-Install-blue.svg
+    :target: `install`_
+
+.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project
+
+.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Download-blue.svg
+    :target: https://pypi.org/pypi/afwf-github#files
+
+
+Welcome to ``afwf_github`` Documentation
+==============================================================================
+.. image:: https://afwf-github.readthedocs.io/en/latest/_static/afwf_github-logo.png
+    :target: https://afwf-github.readthedocs.io/en/latest/
+
+It is an `Alfred Workflow <https://www.alfredapp.com/workflows/>`_ for GitHub operations. There already is a PHP `alfred-github-workflow <https://github.com/gharlan/alfred-github-workflow>`_ library for this. But the searching is based on Alfred built-in word level filtering, which doesn't allow any typo, fuzzy, and full text search. This project aims to provide the best searching experience powered by `tantivy <https://github.com/quickwit-oss/tantivy>`_ (via `sayt2 <https://github.com/MacHu-GWU/sayt2-project>`_), a Rust-based full-text search engine.
+
+
+Install
+------------------------------------------------------------------------------
+1. Make sure you have `Alfred 5 + <https://www.alfredapp.com/>`_ installed and bought the `Power Pack <https://www.alfredapp.com/shop/>`_.
+2. Go to `Release <https://github.com/MacHu-GWU/afwf_github-project/releases>`_, download the latest release.
+3. Double click the file to install.
+4. Prepare your GitHub Personal Access Token: go to https://github.com/settings/tokens, create a new token, make sure you checked ``repo -> public_repo``, ``admin:org -> read:org``, ``admin:enterprise -> read:enterprise`` so the workflow can get your public repo name and url information. If you want to get your private repo as well, you should check ``repo (Full control of private repositories)``.
+
+
+Usage
+------------------------------------------------------------------------------
+1. Configuration.
+
+    In Alfred UI, type ``gh-config``, it should open the ~/.alfred-afwf/afwf_github/config.json``
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/2acff3ad-8a90-4326-8f64-3a54df2da11f
+
+2. Build Index
+
+    In Alfred UI, type ``gh-rebuild-index``, it should start to crawl your GitHub repos. It will take a while to finish. You can check the progress in the ``~/.alfred-afwf/afwf_github/.repo_index/``
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/59ce941d-a22a-4fb5-8013-c6a14ec5ca56
+
+3. Search GitHub
+
+    In Alfred UI, type ``gh ${query}``, it should show the following UI:
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/57ea7aa5-d2e0-4b73-8e66-632453418d92
+
+4. Open Git Repo in Browser
+
+    Copy any absolute path of a file in any git repo, type ``gh-view-in-browser ${path}`` then hit ``Enter``, it should open the repo in browser.
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/e863fac8-e9b0-4301-93c0-d745059e4346
+
+
+Trouble Shooting
+------------------------------------------------------------------------------
+1. ``gh ${query}`` doesn't show any result.
+
+    Check the ``${HOME}/.alfred-afwf/afwf_github/`` folder, if there's no folder name equal to your github username(where to store the index), it means the Workflow failed to crawl your GitHub repos. Please double check ``${HOME}/.alfred-afwf/afwf_github/config.json`` to make sure you have the correct GitHub Personal Access Token.

afwf_github-1.0.1/README.rst

@@ -0,0 +1,95 @@
+
+.. image:: https://readthedocs.org/projects/afwf-github/badge/?version=latest
+    :target: https://afwf-github.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://github.com/MacHu-GWU/afwf_github-project/actions/workflows/main.yml/badge.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/actions?query=workflow:CI
+
+.. image:: https://codecov.io/gh/MacHu-GWU/afwf_github-project/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/MacHu-GWU/afwf_github-project
+
+.. image:: https://img.shields.io/pypi/v/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/pypi/l/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/pypi/pyversions/afwf-github.svg
+    :target: https://pypi.python.org/pypi/afwf-github
+
+.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/afwf_github-project/blob/main/release-history.rst
+
+.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
+    :target: https://github.com/MacHu-GWU/afwf_github-project
+
+------
+
+.. image:: https://img.shields.io/badge/Link-API-blue.svg
+    :target: https://afwf-github.readthedocs.io/en/latest/py-modindex.html
+
+.. image:: https://img.shields.io/badge/Link-Install-blue.svg
+    :target: `install`_
+
+.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project
+
+.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
+    :target: https://github.com/MacHu-GWU/afwf_github-project/issues
+
+.. image:: https://img.shields.io/badge/Link-Download-blue.svg
+    :target: https://pypi.org/pypi/afwf-github#files
+
+
+Welcome to ``afwf_github`` Documentation
+==============================================================================
+.. image:: https://afwf-github.readthedocs.io/en/latest/_static/afwf_github-logo.png
+    :target: https://afwf-github.readthedocs.io/en/latest/
+
+It is an `Alfred Workflow <https://www.alfredapp.com/workflows/>`_ for GitHub operations. There already is a PHP `alfred-github-workflow <https://github.com/gharlan/alfred-github-workflow>`_ library for this. But the searching is based on Alfred built-in word level filtering, which doesn't allow any typo, fuzzy, and full text search. This project aims to provide the best searching experience powered by `tantivy <https://github.com/quickwit-oss/tantivy>`_ (via `sayt2 <https://github.com/MacHu-GWU/sayt2-project>`_), a Rust-based full-text search engine.
+
+
+Install
+------------------------------------------------------------------------------
+1. Make sure you have `Alfred 5 + <https://www.alfredapp.com/>`_ installed and bought the `Power Pack <https://www.alfredapp.com/shop/>`_.
+2. Go to `Release <https://github.com/MacHu-GWU/afwf_github-project/releases>`_, download the latest release.
+3. Double click the file to install.
+4. Prepare your GitHub Personal Access Token: go to https://github.com/settings/tokens, create a new token, make sure you checked ``repo -> public_repo``, ``admin:org -> read:org``, ``admin:enterprise -> read:enterprise`` so the workflow can get your public repo name and url information. If you want to get your private repo as well, you should check ``repo (Full control of private repositories)``.
+
+
+Usage
+------------------------------------------------------------------------------
+1. Configuration.
+
+    In Alfred UI, type ``gh-config``, it should open the ~/.alfred-afwf/afwf_github/config.json``
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/2acff3ad-8a90-4326-8f64-3a54df2da11f
+
+2. Build Index
+
+    In Alfred UI, type ``gh-rebuild-index``, it should start to crawl your GitHub repos. It will take a while to finish. You can check the progress in the ``~/.alfred-afwf/afwf_github/.repo_index/``
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/59ce941d-a22a-4fb5-8013-c6a14ec5ca56
+
+3. Search GitHub
+
+    In Alfred UI, type ``gh ${query}``, it should show the following UI:
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/57ea7aa5-d2e0-4b73-8e66-632453418d92
+
+4. Open Git Repo in Browser
+
+    Copy any absolute path of a file in any git repo, type ``gh-view-in-browser ${path}`` then hit ``Enter``, it should open the repo in browser.
+
+    .. image:: https://github.com/MacHu-GWU/afwf_github-project/assets/6800411/e863fac8-e9b0-4301-93c0-d745059e4346
+
+
+Trouble Shooting
+------------------------------------------------------------------------------
+1. ``gh ${query}`` doesn't show any result.
+
+    Check the ``${HOME}/.alfred-afwf/afwf_github/`` folder, if there's no folder name equal to your github username(where to store the index), it means the Workflow failed to crawl your GitHub repos. Please double check ``${HOME}/.alfred-afwf/afwf_github/config.json`` to make sure you have the correct GitHub Personal Access Token.

afwf_github-1.0.1/afwf_github/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

afwf_github-1.0.1/afwf_github/api.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

afwf_github-1.0.1/afwf_github/cache.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+"""
+Factory for diskcache instances used to store GitHub API responses.
+
+Each GitHub user gets their own cache directory under their per-user data
+directory. sayt2 datasets manage their own internal search result cache
+separately — this module only covers GitHub API response caching.
+"""
+
+from pathlib import Path
+
+from diskcache import Cache
+
+
+def make_cache(dir_cache: Path) -> Cache:
+    """Create a ``diskcache.Cache`` at *dir_cache*.
+
+    diskcache creates the directory if it does not exist, so callers do not
+    need to ensure the path exists beforehand.
+    """
+    return Cache(dir_cache)

afwf_github-1.0.1/afwf_github/cli.py

@@ -0,0 +1,295 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import json
+import typing as T
+import functools
+from pathlib import Path
+from functools import cached_property
+
+import fire
+import afwf.api as afwf
+import git_web_url.api as gwu
+from git_web_url.exc import NotGitRepoError
+
+from .config import Config
+from .paths import path_enum
+from .dataset import create_repo_dataset
+
+_CONFIG_TEMPLATE = {
+    "pac_token": None,
+    "pac_token_home_secret_toml_path": None,
+    "cache_expire": 2_592_000,
+}
+
+_log_error = afwf.log_error(
+    log_file=path_enum.path_error_log,
+    tb_limit=10,
+)
+
+
+def _error_sf(exc: Exception) -> afwf.ScriptFilter:
+    item = afwf.Item(
+        title=f"{type(exc).__name__}: {exc}",
+        subtitle=f"Press Enter to open the error log: {path_enum.path_error_log}",
+        icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+        valid=True,
+    )
+    item.open_file(str(path_enum.path_error_log))
+    return afwf.ScriptFilter(items=[item])
+
+
+def _config_error_sf(config_path: Path) -> afwf.ScriptFilter:
+    item = afwf.Item(
+        title=f"Config file not found: {config_path}",
+        subtitle="Press Enter to open the setup guide on GitHub",
+        icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+        valid=True,
+    )
+    item.open_url("https://github.com/MacHu-GWU/afwf_github-project")
+    return afwf.ScriptFilter(items=[item])
+
+
+def require_config(method: T.Callable) -> T.Callable:
+    """Decorator that resolves and loads config before calling a CLI method.
+
+    Resolution order:
+    1. If ``self.config_file`` is set, load from that path.
+    2. Otherwise use the default path (``path_enum.path_config_json``).
+
+    On any failure (file missing, parse error) the decorator outputs a
+    single error ``Item`` that opens the project README on Enter, then
+    returns early so the wrapped method is never called.
+
+    On success, ``self._config`` is populated and the wrapped method runs
+    normally.
+
+    ``functools.wraps`` is still required in Python 3.10+ to copy
+    ``__name__``, ``__doc__``, ``__wrapped__``, etc. onto the wrapper —
+    ``ParamSpec`` (added in 3.10) improves type-checker inference for
+    decorators but does not replace ``functools.wraps``.
+    """
+
+    @functools.wraps(method)
+    def wrapper(self: "Command", *args, **kwargs):
+        if self.config_file is not None:
+            config_path = Path(self.config_file).expanduser().resolve()
+        else:
+            config_path = path_enum.path_config_json
+
+        if not config_path.exists():
+            _config_error_sf(config_path).send_feedback()
+            return
+
+        try:
+            self._config = Config.load(config_path)
+        except Exception:
+            _config_error_sf(config_path).send_feedback()
+            return
+
+        return method(self, *args, **kwargs)
+
+    return wrapper
+
+
+class Command:
+    """Alfred GitHub Workflow CLI.
+
+    All subcommands accept an optional ``--config-file`` argument (absolute
+    or relative path).  When omitted, config is loaded from the default
+    location via ``default_config``.
+    """
+
+    def __init__(self, config_file: str | None = None):
+        self.config_file = config_file
+        self._config: Config | None = None
+
+    @cached_property
+    def default_config(self) -> Config:
+        """Load config from the default path (``~/.alfred-afwf/afwf_github/config.json``)."""
+        return Config.load(path_enum.path_config_json)
+
+    @afwf.log_error(
+
+    )
+    def edit_config(self) -> None:
+        """Script Filter: open config.json in the default editor.
+
+        Creates a blank template at the default path if the file does not yet
+        exist, then opens it via Alfred's Open File action.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github edit-config
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github edit-config
+        """
+        @_log_error
+        def _run():
+            config_path = path_enum.path_config_json
+            if not config_path.exists():
+                config_path.parent.mkdir(parents=True, exist_ok=True)
+                config_path.write_text(json.dumps(_CONFIG_TEMPLATE, indent=4))
+            item = afwf.Item(
+                title="Open and edit config.json",
+                subtitle=str(config_path),
+                icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.file),
+            )
+            item.open_file(str(config_path))
+            afwf.ScriptFilter(items=[item]).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    def view_in_browser(self, path: str = "") -> None:
+        """Script Filter: given a local file or directory path, open its GitHub URL in the browser.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github view-in-browser --path '{query}'
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github view-in-browser --path '{query}'
+        """
+        @_log_error
+        def _run():
+            if not path.strip():
+                afwf.ScriptFilter(
+                    items=[
+                        afwf.Item(
+                            title="Type or paste the absolute path of a local file or directory"
+                        )
+                    ]
+                ).send_feedback()
+                return
+
+            try:
+                url = gwu.get_web_url(Path(path))
+                item = afwf.Item(
+                    title=f"Open in browser: {url}",
+                    subtitle=f"Local path: {path}",
+                    icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.internet),
+                )
+                item.open_url(url)
+            except NotGitRepoError:
+                item = afwf.Item(
+                    title=f"Not a git repository path: {path}",
+                    subtitle="Only paths inside a git repo with a remote can be opened in browser",
+                    icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+                    valid=False,
+                )
+
+            afwf.ScriptFilter(items=[item]).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    def search_repo(self, query: str = "") -> None:
+        """Script Filter: search GitHub repositories in the local index.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github search-repo --query '{query}'
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github search-repo --query '{query}'
+        """
+        @_log_error
+        def _run():
+            if not query.strip():
+                afwf.ScriptFilter(
+                    items=[afwf.Item(title="Type to search GitHub repositories ...")]
+                ).send_feedback()
+                return
+
+            dataset = create_repo_dataset(config=self._config)
+            result = dataset.search(query=query, limit=50)
+
+            if not result.hits:
+                afwf.ScriptFilter(
+                    items=[
+                        afwf.Item(
+                            title=f"No repository found for: {query!r}",
+                            icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.error),
+                            valid=False,
+                        )
+                    ]
+                ).send_feedback()
+                return
+
+            items = []
+            for hit in result.hits:
+                repo = hit.source
+                account_name = repo["acc"]
+                repo_name = repo["repo"]
+                repo_description = repo.get("desc", "No description")
+                url = f"https://github.com/{account_name}/{repo_name}"
+                item = afwf.Item(
+                    title=f"{account_name}/{repo_name}",
+                    subtitle=repo_description,
+                    autocomplete=f"{account_name}/{repo_name}",
+                )
+                item.open_url(url)
+                items.append(item)
+            afwf.ScriptFilter(items=items).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    def rebuild_index(self) -> None:
+        """Script Filter: show a single item that triggers ``rebuild-index-action`` on Enter.
+
+        Alfred Script field (dev):
+            .venv/bin/afwf-github rebuild-index
+
+        Alfred Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github rebuild-index
+        """
+        @_log_error
+        def _run():
+            bin_cli = Path(sys.executable).parent / "afwf-github"
+            cmd = f"{bin_cli} rebuild-index-action"
+            if self.config_file is not None:
+                cmd += f" --config-file {self.config_file!r}"
+
+            item = afwf.Item(
+                title="Rebuild Index for GitHub Alfred Workflow",
+                subtitle="Hit Enter to rebuild — may take 10–20 seconds",
+                icon=afwf.Icon.from_image_file(path=afwf.IconFileEnum.reset),
+            )
+            item.run_script(cmd)
+            afwf.ScriptFilter(items=[item]).send_feedback()
+
+        try:
+            _run()
+        except Exception as e:
+            _error_sf(e).send_feedback()
+
+    @require_config
+    @_log_error
+    def rebuild_index_action(self) -> None:
+        """Rebuild the local repo search index by re-fetching data from GitHub.
+
+        Called by Alfred's Run Script widget — NOT a Script Filter.
+
+        Alfred Run Script field (dev):
+            .venv/bin/afwf-github rebuild-index-action
+
+        Alfred Run Script field (prod):
+            ~/.local/bin/uvx --from afwf_github==<ver> afwf-github rebuild-index-action
+        """
+        create_repo_dataset(config=self._config).search(
+            query="",
+            refresh=True,
+        )
+
+
+def run():
+    fire.Fire(Command)

afwf_github-1.0.1/afwf_github/config.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+import json
+from pathlib import Path
+from functools import cached_property
+
+from pydantic import BaseModel, ConfigDict, model_validator
+from github import Github, Auth
+from home_secret_toml.api import hs
+
+from .paths import path_enum
+
+path_config_json = path_enum.path_config_json
+
+
+class Config(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    pac_token: str | None = None
+    pac_token_home_secret_toml_path: str | None = None
+    cache_expire: int = 30 * 24 * 3600
+
+    @model_validator(mode="after")
+    def check_pac_token(self):
+        if self.pac_token is None and self.pac_token_home_secret_toml_path is None:
+            raise ValueError("Must provide pac_token or pac_token_home_secret_toml_path")
+        return self
+
+    @classmethod
+    def load(cls, path: Path) -> "Config":  # pragma: no cover
+        return cls.model_validate(json.loads(path.read_text()))
+
+    def dump(self, path: Path):  # pragma: no cover
+        path.write_text(self.model_dump_json(indent=4))
+
+    @cached_property
+    def gh(self):
+        if self.pac_token is not None:
+            pac_token = self.pac_token
+        elif self.pac_token_home_secret_toml_path is not None:
+            pac_token = hs.v(self.pac_token_home_secret_toml_path)
+        else:
+            raise ValueError("Must provide pac_token or pac_token_home_secret_toml")
+        return Github(auth=Auth.Token(pac_token))