h2h-dev-tools 0.2.1__tar.gz

h2h_dev_tools-0.2.1/.githooks/commit-msg

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+message_file=$1
+first_line="$(sed -n '1p' "$message_file")"
+
+if [[ "$first_line" == Merge\ * ]] \
+    && git rev-parse --verify MERGE_HEAD >/dev/null 2>&1; then
+    exit 0
+fi
+
+pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9._/-]+\))?(!)?: .+'
+if [[ ! "$first_line" =~ $pattern ]]; then
+    printf 'Commit message must follow Conventional Commits: %s\n' \
+        "$first_line" >&2
+    exit 1
+fi

h2h_dev_tools-0.2.1/.githooks/pre-commit

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+primary="$(scripts/detect-primary-branch.sh)"
+if git rev-parse --verify MERGE_HEAD >/dev/null 2>&1; then
+    exec .githooks/pre-merge-commit
+fi
+[[ -n "$(git branch --show-current)" ]] || {
+    printf 'Commit requires a task branch, not detached HEAD\n' >&2
+    exit 1
+}
+[[ "$(git branch --show-current)" != "$primary" ]] || {
+    printf 'Direct commits on primary are not allowed: %s\n' "$primary" >&2
+    exit 1
+}
+profile="$(.venv/bin/python scripts/check_change_scope.py --index --base HEAD)"
+case "$profile" in
+    documentation) exec .venv/bin/python scripts/check-docs.py --index --base HEAD ;;
+    full) exec scripts/check-fast.sh ;;
+    *) printf 'Unknown check profile: %s\n' "$profile" >&2; exit 1 ;;
+esac

h2h_dev_tools-0.2.1/.githooks/pre-merge-commit

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+primary="$(scripts/detect-primary-branch.sh)"
+[[ "$(git branch --show-current)" == "$primary" ]] || {
+    printf 'Merge commits are permitted only on primary: %s\n' "$primary" >&2
+    exit 1
+}
+exec .venv/bin/python scripts/release-gate.py

h2h_dev_tools-0.2.1/.githooks/pre-rebase

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repository_root="$(git rev-parse --show-toplevel)"
+cd "$repository_root"
+
+primary="$(scripts/detect-primary-branch.sh)"
+rebased_branch="${2:-$(git symbolic-ref --quiet HEAD || true)}"
+rebased_branch="${rebased_branch#refs/heads/}"
+
+if [[ "$rebased_branch" == "$primary" ]]; then
+    printf 'Rebasing primary is not allowed: %s; preserve merge history.\n' \
+        "$primary" >&2
+    exit 1
+fi

h2h_dev_tools-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: Publish to PyPI
+
+on:
+  push:
+    paths:
+      - pyproject.toml
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Exact project version to publish, including the first release
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    if: >-
+      ${{ github.ref ==
+      format('refs/heads/{0}', github.event.repository.default_branch) }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      publish: ${{ steps.version.outputs.publish }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Install declared build dependencies
+        run: |
+          python scripts/install-ci-dependencies.py packaging build hatchling
+      - name: Select explicitly requested version or push transition
+        id: version
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+          REQUESTED_VERSION: ${{ inputs.version }}
+          EVENT_NAME: ${{ github.event_name }}
+        run: python scripts/select-publish-version.py
+      - name: Build and verify distributions
+        if: steps.version.outputs.publish == 'true'
+        run: >-
+          python scripts/build-and-verify-distributions.py
+          --output-directory dist
+      - name: Store distributions
+        if: steps.version.outputs.publish == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: validate
+    if: needs.validate.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

h2h_dev_tools-0.2.1/.github/workflows/windows-process.yml

@@ -0,0 +1,31 @@
+name: Windows process ownership
+
+on:
+  push:
+    paths:
+      - src/h2h_dev_tools/process.py
+      - tests/test_process*.py
+      - pyproject.toml
+      - .github/workflows/windows-process.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  windows-process:
+    runs-on: windows-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Install project-local test environment
+        run: |
+          python -m venv .venv
+          .venv/Scripts/python -m pip install ".[dev]"
+      - name: Verify Windows Job ownership and command execution
+        run: >-
+          .venv/Scripts/python -B -m pytest -p no:cacheprovider
+          tests/test_process.py tests/test_process_integration.py

h2h_dev_tools-0.2.1/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv
+__pycache__/
+*.egg-info/
+*.py[cod]
+build/
+dist/
+htmlcov/
+node_modules
+package-lock.json
+uv.lock

h2h_dev_tools-0.2.1/.markdownlint-cli2.jsonc

@@ -0,0 +1,25 @@
+{
+  "globs": [
+    "**/*.md",
+    "!**/.lake/**",
+    "!**/.mypy_cache/**",
+    "!**/.pytest_cache/**",
+    "!**/.ruff_cache/**",
+    "!**/.venv/**",
+    "!**/*.egg-info/**",
+    "!**/build/**",
+    "!**/dist/**",
+    "!**/node_modules/**"
+  ],
+  "config": {
+    "default": true,
+    "MD013": {
+      "line_length": 88,
+      "code_blocks": false,
+      "tables": false
+    },
+    "MD024": {
+      "siblings_only": true
+    }
+  }
+}

h2h_dev_tools-0.2.1/.release/dependency-audit.json

@@ -0,0 +1,98 @@
+{
+  "checked_at": "2026-10-11T08:55:45+00:00",
+  "manifest_sha256": "9b9b06499ac50d3669becf22ac2223879fe1acabcb92ac7606fa8feebf8eaba2",
+  "node": [
+    {
+      "declared": ">=0.23.2",
+      "latest": "0.23.3",
+      "latest_satisfies": true,
+      "name": "markdownlint-cli2",
+      "registry_url": "https://www.npmjs.com/package/markdownlint-cli2"
+    }
+  ],
+  "project_version": "0.2.1",
+  "python": [
+    {
+      "declared": "hatchling>=1.32.0",
+      "group": "build",
+      "latest": "1.32.4",
+      "latest_satisfies": true,
+      "name": "hatchling",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/hatchling/",
+      "release_notes": "https://hatch.pypa.io/dev/history/hatchling/",
+      "url": "https://pypi.org/project/hatchling/"
+    },
+    {
+      "declared": "packaging>=26.0",
+      "group": "runtime",
+      "latest": "26.3",
+      "latest_satisfies": true,
+      "name": "packaging",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/packaging/",
+      "release_notes": null,
+      "url": "https://pypi.org/project/packaging/"
+    },
+    {
+      "declared": "build>=1.5.0",
+      "group": "optional:dev",
+      "latest": "1.6.1",
+      "latest_satisfies": true,
+      "name": "build",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/build/",
+      "release_notes": "https://build.pypa.io/en/stable/changelog.html",
+      "url": "https://pypi.org/project/build/"
+    },
+    {
+      "declared": "hatchling>=1.32.0",
+      "group": "optional:dev",
+      "latest": "1.32.4",
+      "latest_satisfies": true,
+      "name": "hatchling",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/hatchling/",
+      "release_notes": "https://hatch.pypa.io/dev/history/hatchling/",
+      "url": "https://pypi.org/project/hatchling/"
+    },
+    {
+      "declared": "mypy>=2.3.1",
+      "group": "optional:dev",
+      "latest": "2.4.0",
+      "latest_satisfies": true,
+      "name": "mypy",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/mypy/",
+      "release_notes": "https://github.com/python/mypy/blob/master/CHANGELOG.md",
+      "url": "https://pypi.org/project/mypy/"
+    },
+    {
+      "declared": "pytest>=9.1.1",
+      "group": "optional:dev",
+      "latest": "9.1.1",
+      "latest_satisfies": true,
+      "name": "pytest",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/pytest/",
+      "release_notes": "https://docs.pytest.org/en/stable/changelog.html",
+      "url": "https://pypi.org/project/pytest/"
+    },
+    {
+      "declared": "ruff>=0.16.4",
+      "group": "optional:dev",
+      "latest": "0.17.0",
+      "latest_satisfies": true,
+      "name": "ruff",
+      "python_3_14": true,
+      "registry_url": "https://pypi.org/project/ruff/",
+      "release_notes": "https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md",
+      "url": "https://pypi.org/project/ruff/"
+    }
+  ],
+  "review": {
+    "note": "Release 0.2.1 consumer-integration follow-up: registry candidates remain hatchling 1.32.4, packaging 26.3, build 1.6.1, mypy 2.4.0, pytest 9.1.1, Ruff 0.17.0 and markdownlint-cli2 0.23.3, all within existing lower bounds and Python 3.14 support. Reviewed official notes at https://hatch.pypa.io/dev/history/hatchling/ https://build.pypa.io/en/stable/changelog.html https://packaging.pypa.io/en/stable/changelog.html https://mypy.readthedocs.io/en/stable/changelog.html https://docs.pytest.org/en/stable/changelog.html https://github.com/astral-sh/ruff/releases/tag/0.17.0 and https://github.com/DavidAnson/markdownlint-cli2/blob/v0.23.3/CHANGELOG.md during this integration. Explicit py314 and selected Ruff rules, standard strict mypy, Node 26.10.0; no changed bounds or pin exceptions. The prior 0.2.0 full gate passed 262 tests and isolated wheel checks. This follow-up only splits one diagnostic string to satisfy consumer E501, without changing its text or runtime behavior; 6 distribution checks and Ruff/mypy/Markdown passed. Fresh 0.2.1 sdist-derived wheel verified all exported components offline. A new clean environment normally resolved the explicit 0.2.1 candidate plus packaging 26.3; package and metadata origins and all original installed wheel members except rewritten RECORD matched the wheel bytes. All six consumer snapshots regenerated from that installed candidate. Windows native remains unexecuted on macOS.",
+    "status": "reviewed"
+  },
+  "schema": "h2h.dependency-audit.v1"
+}

h2h_dev_tools-0.2.1/AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md
+
+## 政策與溝通
+
+- 本檔是本 repository 唯一代理開發政策；可執行細節以 scripts 與設定為準。
+- 最終回覆使用繁體中文；程式碼、命令與 commit message 可使用英文。
+- 不得為了承載回覆新增 Markdown 文件；README 與文件只記錄長期使用契約。
+- 開始實作須說明品質優先，不以最小修改或向後相容限制設計。
+  完成時如實說明具體取捨、介面變化及是否恰好相容。
+- 依 SOLID、KISS、YAGNI、內聚性與低耦合決定抽象邊界。必要局部重構可納入；
+  實質擴大任務、改變未涵蓋公開行為或資料遷移須先取得使用者同意。
+- 直接涉及的 legacy compatibility path 應移除，不保留 shim；不清理無關程式。
+
+## 工具責任
+
+- 本專案擁有跨 H2H repository 的開發工具、可安裝 CLI 與可重建工具快照。
+  不擁有 Core schema、runtime facade、adapter 行為或各 consumer 的業務 gate。
+- 共用 Python 實作的唯一手動維護來源是 `src/h2h_dev_tools/`。
+  Consumer 的 generated snapshot 必須由 `h2h-dev-tools sync` 產生，禁止手改。
+- Consumer hooks 使用納入自身 Git tree 的 snapshot，離線驗證完整 payload 與
+  manifest；不得以任意 sibling checkout 或已安裝的最新版替換 candidate 工具。
+- Snapshot 更新是明確動作，不可在 hooks、一般 pytest 或 merge gate 中下載、
+  安裝、同步或自動修正檔案。產物來源版本及 payload hash 必須可驗證。
+- Consumer 在 `[tool.h2h-dev-tools].components` 明列使用的機制；generator
+  產生完整依賴集合，verifier 必須核對選擇、檔案集合與 bytes。
+  Schema-1 只由明確的 `migrate-v1` 一次性轉換工具接納；一般 gate 不保留
+  舊格式 fallback。Shell bootstrap 不得依賴尚未建立的 `.venv`。
+- 工具不得依賴 `h2hdb`、consumer runtime、Pillow 或 FastAPI。
+  Consumer 只能在開發流程使用本工具；不得加入 consumer runtime dependencies
+  或由 shipped consumer `src/` import 本工具。
+- 不因外觀相似統一專案特有的 timeout、formal、schema、distribution 或 DB checks。
+  各 repository 的政策與必要驗收仍由該 repository 擁有。
+
+## Git 與整合
+
+- 唯讀分析不建立 branch。修改 tracked files 前使用
+  `scripts/detect-primary-branch.sh` 判定 primary 並建立專用 task branch。
+  本 repository 預期 primary 為 `master`；有歧義時設定 local
+  `workflow.primaryBranch`，不得猜測或連網查詢。
+- 不 stash、reset、clean、覆寫或混入既有使用者修改；dirty checkout 從 committed
+  primary 建立獨立 worktree。Task 與 primary 只需 common ancestor。
+- 所有非 merge commit 使用 Conventional Commits；breaking change 使用 `!`
+  或 `BREAKING CHANGE:`。不得使用 `--no-verify`。
+- 任務完成執行 `scripts/git-flow-merge.sh`，以 `--no-ff` 整合；實際 staged
+  merge candidate 由 pre-merge hook 檢查版本、文件或完整 gate。
+  失敗須 abort merge 並保留 task branch。成功才安全移除 task worktree 及
+  `git branch -d`。合併後 follow-up 使用新 task branch。
+- Primary 禁止 rebase。Hooks 安裝設定 `pull.rebase=false`、primary rebase=false
+  與 `pull.ff=only`。No-op cleanup 只在 task tip 已包含於 primary 時進行。
+- 本機 task branch、commit、merge 及安全清理已獲授權。
+  Fetch、pull、push、remote branch、tag、publish、deploy 及 force 操作
+  必須逐次明確授權；既有 PyPI 設定不等於允許發布。
+
+## 版本與依賴
+
+- `pyproject.toml` 的 `[project].version` 是唯一版本來源，固定 `X.Y.Z`。
+  1.0 前 `Y` 是 compatibility lane；相容 release 遞增 `Z`，breaking 遞增 `Y`
+  並歸零 `Z`。1.0 後使用 Semantic Versioning。
+- 本專案 shipped 開發工具本身就是 release surface；`src/`、CLI、snapshot
+  格式或構建 metadata 的改變須升版。只有本 repo 自用 tests、scripts、hooks、CI、
+  文件或品質設定的修改不升版。未知路徑須 fail closed 並明確分類。
+- 既有專案的一個 task 只升版一次，以獨立
+  `chore(release): bump version to X.Y.Z` commit 提交。
+  Breaking／feature 訊號只採計實際修改 release surface 的 commits。
+- 空 repository 的初次 release 明確限定為 `0.1.0`，須從真正 empty baseline
+  建立並驗證 candidate dependency audit；不是一般版本檢查的豁免。
+- 每次 release 執行 `scripts/audit-dependencies.py --review-note "..."`，人工
+  檢查 release notes、Python 相容性及現有 bounds 外最新版，將與版本及完整
+  dependency manifest 綁定的 `.release/dependency-audit.json` 納入提交。
+  Audit 產生器可連網；commit 與 merge 只能驗證既有 evidence。
+- `requires-python` 使用 `>=3.14`。依賴原則使用 `>=` lower bound，合理 upper
+  bound 或排除須有具體相容性理由；不得為求純 stdlib 重寫 PEP 440／508 parser。
+- 單一乾淨 checkout 必須可重建；不得固定依賴 sibling repo。
+  不提交或使用 `uv.lock`、`package-lock.json` 作為重建輸入。
+- Python tools 來自 `.venv`；Markdown tool 來自本 repo `node_modules`。
+  Node 安裝使用 `npm install --package-lock=false`。
+
+## 品質與驗收
+
+- `pyproject.toml` 是 Ruff 與 strict mypy 唯一設定來源。使用 Ruff formatter，
+  不使用 Black、`mypy.ini` 或系統全域品質工具。
+- `noqa` 與 `type: ignore` 必須指定規則／error code 並有理由。
+  禁止為了通過檢查而全域放寬設定。停用 Ruff 規則須在設定旁說明。
+- `scripts/format.sh` 明確修改檔案；`scripts/check-fast.sh` 只讀、離線且不寫
+  Ruff／mypy cache。非文件 commit 執行 fast gate。
+- `scripts/check_change_scope.py` 以 exact Git tree/index 差異選擇 profile。
+  Documentation gate 從 candidate 匯出 Markdown，驗 whitespace、README reference
+  及本機 Markdown lint。未知路徑、mode/type 變化與空差異不得降級為文件。
+- `scripts/release-gate.py` 驗證實際 staged two-parent merge candidate，執行版本
+  及適用 profile，檢查前後 candidate 一致；失敗不得產生 merge commit。
+- Full gate 執行 fast、完整離線 pytest、fresh sdist-derived wheel build 及隔離
+  installed wheel／CLI smoke。明確手動呼叫 fast/full 不因文件差異而降級。
+- Wheel smoke 僅複製已安裝 `packaging` distribution 供離線 resolver，禁止借用
+  editable source 或整個 development site。此結果不代表 registry-backed clean
+  dependency resolution；需要該證據時另以明確 wheels／index 執行並分別回報。
+- 新功能涵蓋正常、邊界、錯誤路徑；bug fix 加 regression test。Git 測試使用
+  disposable local repositories；不連 production、live account 或外部 network。
+  Flaky 視為失敗；skip/xfail 須理由，xfail 預設 strict。
+- GitHub Actions 只保留 trusted publishing 或本機無法驗證的平台檢查，
+  不複製另一套一般 gate。首次發布可明確 dispatch exact version，仍須 default
+  branch guard；一般 push 必須是已存在版本的遞增才發布。
+
+## 完成回報
+
+說明品質優先是否遵守及具體取捨；判定不向後相容或品質優先後恰好相容，列明
+介面／格式影響與移除的 compatibility path。若 breaking，判斷一次性轉換是否
+可行、是否已提供、用法與限制；不可行時精確說明保留及人工重建範圍。
+回報版本、impact、dependency audit、commits、檢查及未執行項目、primary 與 merge
+commit、task branch/worktree 清理狀態，以及是否仍未 push、publish、deploy。