paperful 1.1.0__tar.gz

paperful-1.1.0/.dockerignore

@@ -0,0 +1,35 @@
+.git
+.github
+.venv
+.cursor
+.pytest_cache
+.coverage
+htmlcov
+__pycache__
+*.pyc
+*.pyo
+.DS_Store
+.env
+compose.override.yaml
+docker-compose.override.yml
+
+# Personal / runtime — never bake into the image
+config.toml
+out/
+state/
+packs/
+/data/
+
+# Docs site / build noise
+docs/_build/
+_site/
+website/
+*.md
+!README.md
+tests/
+Makefile
+scripts/
+CONTRIBUTING.md
+CHANGELOG.md
+LICENSE
+.readthedocs.yml

paperful-1.1.0/.env.example

@@ -0,0 +1,49 @@
+# Copy to .env (gitignored). Compose reads this for variable substitution.
+#
+#   cp .env.example .env
+# Host PAPERFUL_DATA → /data (config.toml, packs/, state/).
+# Host PAPERFUL_OUT  → /data/out (PDF mirror). Separate mounts by default.
+# Zotero Storage is not a Compose volume.
+
+# Durable data directory mounted at /data (config.toml, packs/, state/).
+# Preferred (outside the git root):
+PAPERFUL_DATA=../paperful-data
+# Keep your current repo-local config/state without moving files:
+# PAPERFUL_DATA=.
+
+# PDF mirror mounted at /data/out (separate from PAPERFUL_DATA).
+PAPERFUL_OUT=../paperful-out
+# Repo-local out/ (only when PAPERFUL_DATA=.):
+# PAPERFUL_OUT=./out
+
+# Docker image pack (build arg). Rebuild after changing:
+#   docker compose build --no-cache
+# light — core + [serve] (Compose default when unset; CI uses this)
+# heavy — also [llm] [rag] [browser-agent] for a full local env
+PAPERFUL_IMAGE_MODE=heavy
+
+# Host where Zotero's local API listens (Docker Desktop → host.docker.internal).
+# On Linux with network_mode: host you can use localhost instead.
+PAPERFUL_ZOTERO_HOST=host.docker.internal
+
+# Host Ollama for Compose (same gateway). Outside Docker, Paperful falls back to
+# 127.0.0.1 when this is host.docker.internal. Docker Desktop: default Ollama
+# loopback is enough. Linux Engine: OLLAMA_HOST=0.0.0.0. See docs/llm.md#docker.
+PAPERFUL_OLLAMA_HOST=host.docker.internal
+
+# Free key from https://openalex.org/settings/api — never commit the real value.
+# OPENALEX_API_KEY=
+
+# Optional. Semantic Scholar works without a key. Request one for heavy use
+# (it arrives by email): https://www.semanticscholar.org/product/api#api-key-form
+# SEMANTIC_SCHOLAR_API_KEY=
+
+# Optional. Google Scholar link discovery via SerpApi. Also set [serpapi].enabled
+# and [serpapi].max_calls (default 20; 0 = unlimited). See docs/serpapi.md.
+# SERPAPI_API_KEY=
+
+# Optional. Self-hosted or cloud Twenty CRM. Also set [twenty].enabled and
+# [twenty].base_url in config.toml. Used by twenty lookup and reachout --lookup.
+# See docs/config.md.
+# TWENTY_API_KEY=
+# TWENTY_BASE_URL=

paperful-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev --extra serve
+      - run: uv run pytest -m "not docs" --cov=paperful --cov-report=term-missing --cov-report=json:coverage.json
+      - name: Upload coverage report
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-json
+          path: coverage.json
+          if-no-files-found: error
+      - name: Workbench API smoke (preview token path)
+        run: |
+          uv run pytest tests/test_ui_grab.py tests/test_ui_commands.py -q
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build local image
+        run: docker compose build
+      - name: Compose config
+        run: docker compose config >/dev/null
+      - name: Smoke help and doctor without Zotero
+        # Compose-first claim: this job is the proof, not pytest-only.
+        # No live Zotero on the runner → doctor exit 2 (Zotero row red).
+        # Must not fail the workflow solely because the API is missing.
+        run: |
+          data="$(mktemp -d)"
+          out="$(mktemp -d)"
+          # Image runs as uid 1000; mktemp is 0700 for the runner uid — open the mounts.
+          chmod 0777 "$data" "$out"
+          cp config.example.toml "$data/config.toml"
+          export PAPERFUL_DATA="$data"
+          export PAPERFUL_OUT="$out"
+          docker compose run --rm -T paperful --help
+          set +e
+          docker compose run --rm -T paperful doctor --no-guide
+          code=$?
+          set -e
+          test "$code" -eq 2

paperful-1.1.0/.github/workflows/coverage-badge.yml

@@ -0,0 +1,40 @@
+# Refresh badges/coverage.json after a green CI run on main.
+# The commit message skips CI so this cannot loop.
+name: Coverage badge
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  contents: write
+  actions: read
+
+jobs:
+  badge:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.event == 'push' &&
+      github.repository == 'glen-w/Paperful'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - uses: actions/download-artifact@v4
+        with:
+          name: coverage-json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+      - name: Write Shields endpoint
+        run: python3 scripts/coverage_badge.py coverage.json badges/coverage.json
+      - name: Commit badge when the percentage changes
+        run: |
+          git add badges/coverage.json
+          git diff --cached --quiet && exit 0
+          git -c user.name="github-actions[bot]" \
+              -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
+              commit -m "chore: refresh coverage badge [skip ci]"
+          git push

paperful-1.1.0/.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+# Advisory docs build — does not gate merges (see continue-on-error).
+# Merge blockers live in ci.yml (pytest + Docker). Maintainers: DOCS_STRICT=1 make docs locally.
+name: Docs
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra docs --group dev
+      - name: Guide corpus + Sphinx build (warnings OK)
+        run: |
+          uv run pytest tests/test_sphinx_docs.py -m docs -q
+          make docs
+      - name: Upload docs HTML
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html/
+          if-no-files-found: warn

paperful-1.1.0/.github/workflows/pages.yml

@@ -0,0 +1,48 @@
+name: Deploy website + Sphinx docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "website/**"
+      - "docs/**"
+      - "scripts/release/build_docs.sh"
+      - "scripts/release/assemble_pages_site.sh"
+      - "scripts/release/build_docs.sh"
+      - "tests/test_sphinx_docs.py"
+      - "pyproject.toml"
+      - "Makefile"
+      - ".github/workflows/pages.yml"
+      - "website/CNAME"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra docs --group dev
+      - name: Guide corpus check (advisory)
+        continue-on-error: true
+        run: uv run pytest tests/test_sphinx_docs.py -m docs -q
+      - name: Assemble site (Sphinx warnings do not fail deploy)
+        run: bash scripts/release/assemble_pages_site.sh
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v4

paperful-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+# Upload release wheels to PyPI (trusted publishing).
+# One-time setup: https://docs.pypi.org/trusted-publishers/
+#   Owner: glen-w  Repo: Paperful  Workflow: publish.yml  Environment: pypi
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Pre-release checks
+        run: bash scripts/release/pre_release.sh
+      - name: Build packages
+        run: uv build
+      - name: Verify dist artifacts
+        run: bash scripts/release/pre_release.sh --dist-only
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

paperful-1.1.0/.gitignore

@@ -0,0 +1,24 @@
+config.toml
+.venv/
+out/
+state/
+packs/
+# repo-root scratch (tool state, one-off exports). Not paperful/data/.
+/data/
+docs/_build/
+_site/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+/coverage.json
+dist/
+.DS_Store
+.cursor/commands/
+*cookies*.txt
+ezproxy-cookies.txt
+.env
+compose.override.yaml
+docker-compose.override.yml
+assessments/

paperful-1.1.0/.python-version

@@ -0,0 +1 @@
+3.11

paperful-1.1.0/.readthedocs.yml

@@ -0,0 +1,19 @@
+# Optional RTD mirror; production guide ships on GitHub Pages (paperful.app/guide/).
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs