h2hdb-ingest 0.1.0__tar.gz

h2hdb_ingest-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,123 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pyproject.toml
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      bumped: ${{ steps.version.outputs.bumped }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install packaging tools
+        run: python -m pip install --upgrade packaging build
+
+      - name: Check version bump
+        id: version
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import subprocess
+          import tomllib
+
+          from packaging.version import Version
+
+
+          def project_version(document: str) -> Version:
+              return Version(str(tomllib.loads(document)["project"]["version"]))
+
+
+          current = project_version(
+              Path("pyproject.toml").read_text(encoding="utf-8")
+          )
+          previous_document = subprocess.run(
+              ["git", "show", "HEAD~1:pyproject.toml"],
+              check=False,
+              capture_output=True,
+              text=True,
+          )
+          previous = (
+              project_version(previous_document.stdout)
+              if previous_document.returncode == 0
+              else None
+          )
+          if previous is not None and current < previous:
+              raise SystemExit(
+                  f"project.version decreased from {previous} to {current}"
+              )
+
+          bumped = previous is None or current > previous
+          output_path = Path(os.environ["GITHUB_OUTPUT"])
+          with output_path.open("a", encoding="utf-8") as output:
+              print(f"current={current}", file=output)
+              print(f"previous={previous or ''}", file=output)
+              print(f"bumped={'true' if bumped else 'false'}", file=output)
+          PY
+
+      - name: Install project and development dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Check formatting
+        run: python -m black --check .
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Type-check
+        run: >-
+          python -m mypy src tests
+          scripts/bootstrap-catalog.py
+
+      - name: Test
+        run: python -m pytest
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Smoke-test wheel
+        run: |
+          WHEEL="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          test -n "$WHEEL"
+          python -m pip install --force-reinstall --no-deps "$WHEEL"
+          python -c "import h2hdb_ingest"
+          h2hdb-ingest --help
+          h2hdb-ingest-bootstrap --help
+
+      - name: Store distributions
+        if: steps.version.outputs.bumped == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: validate
+    if: needs.validate.outputs.bumped == 'true'
+    runs-on: ubuntu-latest
+    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

h2hdb_ingest-0.1.0/.gitignore

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

h2hdb_ingest-0.1.0/AGENTS.md

@@ -0,0 +1,87 @@
+# Agent Instructions
+
+## Project
+
+`h2hdb-ingest` is the filesystem-facing ingest service for H2HDB. Python must
+be run through `uv run --no-sync`, using the repository-local virtual
+environment. The supported Python version is defined by `requires-python` in
+`pyproject.toml`.
+
+## Ownership Boundary
+
+This repository owns:
+
+- filesystem scanning and gallery discovery;
+- `galleryinfo.txt` parsing orchestration;
+- source hashing and deduplication policy;
+- CBZ creation, rebuilding, and final reconciliation;
+- the resident ingest loop and ingest-lease heartbeat orchestration.
+
+Keep the src layout (`src/h2hdb_ingest`); the public import package is
+`h2hdb_ingest`. Do not move the package to the repository root merely to match
+an older project.
+
+The `h2hdb` core package exclusively owns connectors, transactions, database
+schema and migrations, durable queues, token-fenced coordination, catalog
+repositories, and catalog publication. Depend only on core public interfaces;
+do not import connector or repository internals and do not add schema here.
+Catalog publication must follow successful final CBZ reconciliation.
+Prepare new CBZ files without overwriting currently published artifacts. Before
+entering the revision transaction, durably protect every selected artifact from
+pruning. After commit, promote those files to published state. Retain immutable
+published and commit-ambiguous protected artifacts for historical revisions;
+prune only abandoned staging artifacts. Consumer startup performs a
+compatibility check and must never migrate core schema.
+
+CBZ operation uses two distinct, non-nested roots. `artifact_store_path` owns
+content-addressed immutable artifacts and reconciliation state for OPDS;
+`cbz_path` owns only the current friendly-file projection for Komga. Update the
+Komga projection only after catalog publication succeeds, and remove only paths
+recorded as managed in artifact-store state. Never replace or delete an unknown
+file in the Komga root.
+
+Every CBZ-enabled publisher must use the same shared `artifact_store_path` as
+its coordination domain. Acquire the artifact-store publication flock before
+the core database gate and hold it from immediately before catalog publication
+through projection finalization; never acquire these locks in the reverse
+order. The OS releases the flock if a process exits, and the durable pending
+projection journal is the source of truth for crash recovery.
+Persist the current projection's artifact identity and regular-file stat
+signature. Skip a projection copy only when both still match; any external
+mutation must be reverified with an atomic copy.
+
+## Environment and Commands
+
+This is a standalone repository, not a uv workspace. `uv.lock` is ignored and
+must not become a build, test, or runtime input.
+
+```bash
+uv venv --python 3.14
+uv pip install -e ".[dev]"
+uv run --no-sync ruff check .
+uv run --no-sync black --check .
+uv run --no-sync mypy src tests
+uv run --no-sync pytest
+uv run --no-sync python -m build
+```
+
+If the environment is damaged, run `scripts/rebuild-env.sh`.
+
+## Shared Finalization
+
+The repository keeps provider-neutral hooks in `scripts/hooks/`.
+
+- After changing Python, run `bash scripts/hooks/finalize-python.sh`.
+- After changing Markdown, run `bash scripts/hooks/finalize-markdown.sh`.
+
+Do not create agent-specific copies of these implementations.
+
+## Design and Compatibility
+
+The project is pre-1.0. Prefer clear responsibility boundaries and the cleanest
+end state over compatibility shims or deprecated aliases. Follow SOLID
+principles and keep network waits or filesystem work outside core database
+transactions and the database gate.
+
+`CLAUDE.md` documents the same repository rules. Keep both files synchronized
+when changing workflow, ownership, testing, or tooling conventions.

h2hdb_ingest-0.1.0/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides repository guidance to Claude Code and other coding agents.
+
+## Communication
+
+- Claude 必須以繁體中文回答所有對話內容；程式碼、指令、檔名與專有名詞維持原文。
+
+## Project
+
+`h2hdb-ingest` is the filesystem-facing ingest service for H2HDB. It owns
+gallery discovery, `galleryinfo.txt` parsing orchestration, hashing,
+deduplication policy, CBZ creation and reconciliation, and the resident ingest
+loop with its ingest-lease heartbeat.
+
+Keep the modern src layout at `src/h2hdb_ingest`; consumers still import
+`h2hdb_ingest`. Do not flatten it to match older repositories.
+
+The `h2hdb` core package exclusively owns database connectors, transactions,
+schema migrations, durable queues, token fencing, catalog repositories, and
+catalog publication. Use only core public interfaces. Never import connector or
+repository internals, create schema, or publish catalog data before final CBZ
+reconciliation succeeds.
+
+Prepare content-addressed CBZ artifacts without overwriting currently published
+files. Durably protect selected artifacts before the catalog revision
+transaction, then promote them to published state after commit. Retain immutable
+published and commit-ambiguous protected artifacts for historical revisions;
+prune only abandoned staging artifacts. Startup performs only the core schema
+compatibility check and must not run migrations.
+
+CBZ operation uses two distinct, non-nested roots. `artifact_store_path` owns
+content-addressed immutable artifacts and reconciliation state for OPDS;
+`cbz_path` owns only the current friendly-file projection for Komga. Update the
+Komga projection only after catalog publication succeeds, and remove only paths
+recorded as managed in artifact-store state. Never replace or delete an unknown
+file in the Komga root.
+
+Every CBZ-enabled publisher must use the same shared `artifact_store_path` as
+its coordination domain. Acquire the artifact-store publication flock before
+the core database gate and hold it from immediately before catalog publication
+through projection finalization; never acquire these locks in the reverse
+order. The OS releases the flock if a process exits, and the durable pending
+projection journal is the source of truth for crash recovery.
+Persist the current projection's artifact identity and regular-file stat
+signature. Skip a projection copy only when both still match; any external
+mutation must be reverified with an atomic copy.
+
+## Development
+
+This is an independent repository and not part of a uv workspace. `uv.lock` is
+ignored and must not be used by build, test, or runtime workflows. Always run
+Python through `uv run --no-sync` after installing the editable environment.
+
+```bash
+uv venv --python 3.14
+uv pip install -e ".[dev]"
+uv run --no-sync ruff check .
+uv run --no-sync black --check .
+uv run --no-sync mypy src tests
+uv run --no-sync pytest
+uv run --no-sync python -m build
+```
+
+Use `scripts/rebuild-env.sh` to recreate a damaged environment.
+
+## Shared Finalization
+
+Provider-neutral hooks live in `scripts/hooks/` and are shared by humans and
+all coding agents.
+
+- After Python changes, run `bash scripts/hooks/finalize-python.sh`.
+- After Markdown changes, run `bash scripts/hooks/finalize-markdown.sh`.
+
+Do not duplicate their implementation under an agent-specific directory.
+
+## Design
+
+This project is pre-1.0. Prefer the cleanest architecture over compatibility
+shims and deprecated aliases. Follow SOLID principles. Keep filesystem work,
+compression, sleeps, and network operations outside core transactions and the
+database gate.
+
+Keep this document synchronized with `AGENTS.md` whenever ownership, workflow,
+testing, or tooling conventions change.