aicommit-joy 0.1.1__tar.gz

aicommit_joy-0.1.1/.gitignore

@@ -0,0 +1,35 @@
+# 環境變數
+.env
+
+# Python 構建產物
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*$py.class
+
+# 虛擬環境
+.venv/
+venv/
+ENV/
+env/
+
+# IDE 設定
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS 相關
+.DS_Store
+Thumbs.db
+
+# PyPI 發布相關
+*.whl
+*.tar.gz
+
+# UV 鎖定檔案（可選，看團隊需求）
+# uv.lock
+

aicommit_joy-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joy
+
+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.

aicommit_joy-0.1.1/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: aicommit-joy
+Version: 0.1.1
+Summary: AI-powered Git commit message generator using Conventional Commits
+Author: Joy
+License: MIT
+License-File: LICENSE
+Keywords: ai,aicommit,aicommit-cli,aicommitcli,autocommit,automate,automation,cli,commit,commits,conventional-commits,gemini,git,smartcommit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: google-genai>=0.2.2
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# aicommit 🤖
+
+使用 AI 自動生成符合 Conventional Commits 規範的 Git commit 訊息。
+使用 Gemini 2.5 Flash-Lite
+這是速度最快的 Flash 模型，經過最佳化調整，成本效益最高，輸送量也最大。
+
+## ✨ 功能特色
+
+- 🤖 **AI 智能生成**：使用 Google Gemini AI 分析程式碼變更，自動生成專業的 commit 訊息
+- ✏️ **手動編輯**：可以編輯 AI 生成的訊息，保留個人風格
+- ✅ **格式驗證**：自動檢查 commit 訊息是否符合 Conventional Commits 規範
+- 🎯 **繁體中文支援**：生成的訊息使用繁體中文描述
+- 🚀 **全域命令**：安裝後可在任何 Git 專案中直接使用
+
+## 📋 安裝需求
+
+- Python 3.10+
+- Google Gemini API 金鑰
+- Git
+
+## 🚀 快速開始
+
+### 1. 安裝 aicommit
+
+```bash
+# 使用 pip 安裝
+pip install aicommit-joy
+
+# 或使用 pipx（推薦，避免依賴衝突）
+pipx install aicommit-joy
+
+# 或使用 uv（最快速）
+uv tool install aicommit-joy
+```
+
+> 💡 **提示**:
+>
+> - 使用 **pipx** 請先執行 `pip install pipx`，參考 [pipx 官方文檔](https://github.com/pypa/pipx)
+> - 使用 **uv** 請先安裝 uv，參考 [uv 官方文檔](https://docs.astral.sh/uv/)
+
+### 2. 設定 API 金鑰
+
+在您的專案目錄建立 `.env` 檔案：
+
+```bash
+echo "GEMINI_API_KEY=your_gemini_api_key_here" > .env
+```
+
+> **如何取得 API 金鑰？**  
+> 前往 [Google AI Studio](https://aistudio.google.com/apikey) 免費取得您的 Gemini API 金鑰
+
+### 3. 開始使用
+
+```bash
+# 在任何 Git 專案中
+cd /path/to/your/project
+
+# 暫存變更
+git add .
+
+# 執行 aicommit
+aicommit
+```
+
+就這麼簡單！✨
+
+## 📖 使用範例
+
+```bash
+$ cd /path/to/your/project
+$ git add .
+$ aicommit
+
+🤖 AI 正在分析程式碼變更，請稍候...
+
+------------------------------------
+📝 建議訊息: feat: 新增使用者登入功能
+------------------------------------
+
+請選擇操作 (y=使用/e=編輯/n=取消): e
+
+請輸入新的 commit 訊息（按 Enter 確認）:
+feat: 新增使用者登入功能
+> feat: 新增使用者登入與註冊功能
+
+✅ 訊息格式正確！
+📝 更新後的訊息: feat: 新增使用者登入與註冊功能
+
+是否提交此訊息? (y/n): y
+✅ 提交成功！可以使用 git push 上傳
+```
+
+## 🎯 操作選項
+
+執行 `aicommit` 後，您有三個選項：
+
+- **`y`** - 直接使用 AI 生成的訊息提交
+- **`e`** - 編輯訊息後再提交
+- **`n`** - 取消提交
+
+## 📝 Conventional Commits 規範
+
+aicommit 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 規範。
+
+### 允許的 Commit Types
+
+| Type       | 說明                       | 範例                               |
+| ---------- | -------------------------- | ---------------------------------- |
+| `feat`     | 新增功能                   | `feat: 新增使用者登入功能`         |
+| `fix`      | 修復 bug                   | `fix: 修復登入頁面顯示錯誤`        |
+| `docs`     | 文件修改                   | `docs: 更新 API 文件`              |
+| `style`    | 格式修改（不影響程式邏輯） | `style: 調整程式碼縮排`            |
+| `refactor` | 程式碼重構                 | `refactor: 重構資料處理邏輯`       |
+| `perf`     | 效能優化                   | `perf: 優化資料庫查詢效能`         |
+| `test`     | 測試相關                   | `test: 新增登入功能測試`           |
+| `build`    | 建置系統修改               | `build: 更新依賴套件版本`          |
+| `ci`       | CI 設定修改                | `ci: 新增 GitHub Actions 工作流程` |
+| `chore`    | 雜項修改                   | `chore: 更新 .gitignore`           |
+| `revert`   | 恢復先前提交               | `revert: 恢復登入功能變更`         |
+
+### 格式範例
+
+```
+<type>: <subject>
+```
+
+**正確範例**：
+
+- ✅ `feat: 新增使用者登入功能`
+- ✅ `fix: 修復登入頁面顯示錯誤`
+- ✅ `docs: 更新 README 安裝說明`
+
+**錯誤範例**：
+
+- ❌ `feature: 新增功能` （type 錯誤，應為 `feat`）
+- ❌ `feat 新增功能` （缺少冒號）
+- ❌ `feat:` （subject 為空）
+
+## �️ 進階使用
+
+### 查看版本
+
+```bash
+aicommit --version
+```
+
+### 查看幫助
+
+```bash
+aicommit --help
+```
+
+### 更新 aicommit
+
+```bash
+# 使用 pip
+pip install --upgrade aicommit-joy
+
+# 或使用 pipx
+pipx upgrade aicommit-joy
+
+# 或使用 uv
+uv tool upgrade aicommit-joy
+```
+
+### 卸載 aicommit
+
+```bash
+# 使用 pip
+pip uninstall aicommit-joy
+
+# 或使用 pipx
+pipx uninstall aicommit-joy
+
+# 或使用 uv
+uv tool uninstall aicommit-joy
+```
+
+## 🔧 問題排除
+
+### ❌ 找不到 GEMINI_API_KEY
+
+```
+❌ Error: 找不到 GEMINI_API_KEY
+請在當前目錄建立 .env 檔案，內容：GEMINI_API_KEY=你的金鑰
+```
+
+**解決方案**：
+
+1. 確認您的專案目錄中有 `.env` 檔案
+2. 檢查 `.env` 內容格式正確：`GEMINI_API_KEY=your_key_here`
+3. API 金鑰沒有多餘的引號或空格
+
+### ❌ 沒有偵測到暫存的變更
+
+```
+⚠️ 沒有偵測到暫存的變更(Staged Changes)，如有變更請先執行 git add
+```
+
+**解決方案**：先使用 `git add` 暫存您要提交的變更
+
+```bash
+git add .                    # 暫存所有變更
+git add file1.py file2.py   # 暫存特定檔案
+```
+
+### ❌ AI 生成失敗
+
+```
+❌ AI 生成失敗: ...
+```
+
+**可能原因**：
+
+- 網路連線問題
+- API 金鑰無效或過期
+- API 配額已用完
+- 變更內容過大
+
+**解決方案**：
+
+1. 檢查網路連線
+2. 確認 API 金鑰有效
+3. 查看 [Google AI Studio](https://aistudio.google.com/) 配額使用狀況
+
+## 👨‍💻 開發者指南
+
+### 專案結構
+
+```
+aicommit-cli/
+├── aicommit_cli/            # 主要套件
+│   ├── __init__.py       # 套件初始化
+│   ├── core.py           # 核心功能（Git、AI、驗證）
+│   └── cli.py            # CLI 入口點
+├── install.sh            # 自動安裝腳本
+├── pyproject.toml        # 專案配置
+├── LICENSE               # MIT 授權
+└── README.md             # 專案說明
+```
+
+### 執行測試
+
+```bash
+# 建立測試專案
+cd /tmp
+mkdir test-repo
+cd test-repo
+git init
+
+# 建立測試檔案
+echo "# Test" > README.md
+git add README.md
+
+# 測試 aicommit
+aicommit
+```
+
+## 🙏 致謝
+
+- [Google Gemini](https://ai.google.dev/) - 提供強大的 AI 能力
+- [Conventional Commits](https://www.conventionalcommits.org/) - 提供 commit 訊息規範
+
+---
+
+**享受使用 aicommit 的樂趣！** 🚀

aicommit_joy-0.1.1/PUBLISHING.md

@@ -0,0 +1,139 @@
+# 發布 aicommit-cli 到 PyPI
+
+本文檔說明如何發布 aicommit-cli (套件名稱: `aicommit-cli`) 到 PyPI。
+
+## 前置準備
+
+1. **PyPI 帳號**: https://pypi.org/account/register/
+2. **API Token**: https://pypi.org/manage/account/token/
+   - 建立一個新的 API token
+   - 範圍可設為「整個帳號」或「特定專案」
+   - 保存好 token（格式：`pypi-...`）
+
+## 發布流程
+
+### 1. 更新版本號
+
+編輯 `pyproject.toml`，更新版本號：
+
+```toml
+version = "0.1.1"  # 例如從 0.1.0 升級到 0.1.1
+```
+
+### 2. 構建套件
+
+使用 `uv` 構建發行套件：
+
+```bash
+uv build
+```
+
+這會在 `dist/` 目錄生成兩個文件：
+
+- `aicommit-cli-x.x.x.tar.gz` (源碼發行版)
+- `aicommit-cli-x.x.x-py3-none-any.whl` (wheel 套件)
+
+### 3. 檢查套件 (可選但推薦)
+
+```bash
+uv tool run twine check dist/*
+```
+
+### 4. 上傳到 PyPI
+
+使用 API token 上傳：
+
+```bash
+uv tool run twine upload dist/* -u __token__ -p pypi-YOUR_API_TOKEN_HERE
+```
+
+或者使用互動式輸入（系統會提示輸入用戶名和密碼）：
+
+```bash
+uv tool run twine upload dist/*
+# Username: __token__
+# Password: pypi-YOUR_API_TOKEN_HERE
+```
+
+### 5. 驗證發布
+
+訪問 PyPI 頁面確認：
+
+- https://pypi.org/project/aicommit-cli/
+
+測試安裝：
+
+```bash
+pip install aicommit-cli
+aicommit-cli --version
+```
+
+## 測試發布 (推薦首次使用)
+
+在首次發布前，建議先上傳到 TestPyPI 測試：
+
+### 1. 註冊 TestPyPI 帳號
+
+https://test.pypi.org/account/register/
+
+### 2. 建立 TestPyPI API Token
+
+https://test.pypi.org/manage/account/token/
+
+### 3. 上傳到 TestPyPI
+
+```bash
+uv tool run twine upload --repository testpypi dist/* -u __token__ -p YOUR_TESTPYPI_TOKEN
+```
+
+### 4. 從 TestPyPI 安裝測試
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple aicommit-cli
+```
+
+注意：需要 `--extra-index-url` 因為依賴套件（如 `google-genai`）在正式 PyPI。
+
+## 清理構建產物
+
+發布後可以清理：
+
+```bash
+rm -rf dist/ build/ *.egg-info
+```
+
+## 版本號規範
+
+遵循 [Semantic Versioning](https://semver.org/):
+
+- **MAJOR.MINOR.PATCH** (例如 1.2.3)
+  - **MAJOR**: 不兼容的 API 變更
+  - **MINOR**: 向後兼容的功能新增
+  - **PATCH**: 向後兼容的錯誤修復
+
+範例：
+
+- `0.1.0` → `0.1.1`: 錯誤修復
+- `0.1.1` → `0.2.0`: 新增功能
+- `0.2.0` → `1.0.0`: 重大變更或穩定版本
+
+## 常見問題
+
+### 上傳失敗：檔案已存在
+
+PyPI 不允許覆蓋已上傳的版本。需要：
+
+1. 更新版本號
+2. 重新構建
+3. 再次上傳
+
+### Token 認證失敗
+
+確認：
+
+- Username 必須是 `__token__`（兩個底線）
+- Password 是完整的 token（包含 `pypi-` 前綴）
+
+### 依賴套件安裝失敗
+
+確保 `pyproject.toml` 中的依賴版本正確且可用。