foilstack 0.2.0__tar.gz

foilstack-0.2.0/.env.example

@@ -0,0 +1,112 @@
+# Copy to .env and adjust. Never commit .env.
+# Every value here is a placeholder: this file must never hold a real secret.
+
+# Where extracted scans and cached reference images live. The database is
+# separate — it lives in the `postgres-data` volume, and the `backup` service
+# is what protects it.
+FOILSTACK_DATA_DIR=./data
+
+# --- database -------------------------------------------------------------
+# Used by the postgres container and, composed into DATABASE_URL, by the app.
+POSTGRES_USER=foilstack
+POSTGRES_PASSWORD=change-me
+POSTGRES_DB=foilstack
+# Host port for psql and pg_dump. Bound to loopback only.
+POSTGRES_PORT=5434
+
+# --- accounts -------------------------------------------------------------
+# Off means no login screen and no passwords: one implicit owner holds
+# everything, which is what you want running this for yourself. Turn it on for
+# a deployment other people can reach.
+FOILSTACK_MULTI_USER=false
+# Signs session cookies. Anyone holding this can mint a session for any
+# account, so generate your own before turning multi-user on:
+#   python -c 'import secrets; print(secrets.token_urlsafe(48))'
+# The app refuses to start multi-user while this is the development default.
+FOILSTACK_SECRET_KEY=dev-insecure-change-me
+
+FOILSTACK_SUPPORT_URL=https://buymeacoffee.com/foilstack
+
+# --- matching -------------------------------------------------------------
+# The image encoder. Must be the same model that built your catalogue vectors —
+# vectors from two different encoders are not comparable, and the failure is
+# silent nonsense rather than an error.
+EMBEDDER_URL=http://embedder:8100
+EMBED_MODEL=facebook/dinov3-vitl16-pretrain-lvd1689m
+
+# Where Hugging Face weights are cached on the host.
+HF_CACHE_DIR=~/.cache/huggingface
+
+# Matches at or above this cosine similarity are auto-accepted without review.
+# Lower it and you will list cards you never looked at.
+FOILSTACK_AUTO_ACCEPT=0.94
+
+# How far ahead of the runner-up the top match must be. A high score alone is
+# not evidence: reprints share artwork, so the second-place card is usually the
+# same card in a different printing at a very different price.
+FOILSTACK_AUTO_ACCEPT_MARGIN=0.04
+
+# Largest archive the importer will accept, in megabytes.
+FOILSTACK_MAX_ARCHIVE_MB=512
+
+# --- who may sign up -------------------------------------------------------
+# Multi-user only. Turning registration off leaves existing accounts working
+# and stops new ones — the lever for the day a public deployment attracts the
+# wrong attention, without taking the site down on the people already using it.
+FOILSTACK_ALLOW_REGISTRATION=true
+# The setting in between "anyone" and "nobody": registration stays open but
+# asks for a code you handed out. Empty means no code is required.
+FOILSTACK_INVITE_CODE=
+
+# Failed sign-ins allowed per account and per address before the form starts
+# refusing, and the window they are counted over. Generous for someone who has
+# forgotten which password they used; ruinous for a script working a list.
+FOILSTACK_LOGIN_ATTEMPTS=10
+FOILSTACK_LOGIN_WINDOW_S=900
+
+# The disk one account's scans may occupy. 0 means no ceiling, which is right
+# for a self-hosted install where the only account is the person who owns the
+# disk. Set a number wherever strangers can register, because otherwise the
+# amount of disk an account may take is decided by that account.
+FOILSTACK_MAX_ACCOUNT_MB=0
+
+# --- price sync -----------------------------------------------------------
+# Which catalogues the `prices` service keeps fresh. `all` means every game you
+# have ingested, which is almost always what you want: naming games explicitly
+# means a game you ingest later keeps its ingest-day prices for good, and
+# nothing tells you it has stopped being updated.
+FOILSTACK_SYNC_GAMES=all
+# How often it *checks* upstream's build timestamp. It pulls at most once per
+# rebuild, and TCGCSV rebuilds once a day — see https://tcgcsv.com/docs.
+FOILSTACK_SYNC_CHECK_EVERY=21600
+
+# --- backups --------------------------------------------------------------
+# The `backup` service dumps into this host directory. A bind mount, not a
+# named volume: a backup `docker compose down -v` can destroy is not a backup.
+FOILSTACK_BACKUP_DIR=./backups
+# Written as this uid:gid so the dumps are yours, not root's. `id -u`, `id -g`.
+FOILSTACK_BACKUP_UID=1000
+FOILSTACK_BACKUP_GID=1000
+# Dump when the newest one is older than this many seconds (default daily),
+# checking this often. How many to keep is a count, so disk cost is bounded.
+FOILSTACK_BACKUP_INTERVAL=86400
+FOILSTACK_BACKUP_CHECK_EVERY=3600
+FOILSTACK_BACKUP_KEEP=14
+# A floor that catches a truncated dump, not a size target.
+FOILSTACK_BACKUP_MIN_BYTES=4096
+# Timestamps in filenames are local to this zone.
+TZ=UTC
+
+# --- copying the backups off this machine ----------------------------------
+# Everything above protects against failures inside the box. None of it
+# survives the disk dying, because the dumps and the scan mirror sit on the
+# same disk as the database. This is the part that fixes that, and it is off
+# unless you ask for it:
+#
+#   rclone config
+#   docker compose --profile offsite up -d
+#
+# Any rclone remote works; object storage is the cheap answer at this size.
+FOILSTACK_OFFSITE_REMOTE=
+FOILSTACK_OFFSITE_EVERY=86400
+FOILSTACK_RCLONE_CONFIG=~/.config/rclone

foilstack-0.2.0/.git-blame-ignore-revs

@@ -0,0 +1,10 @@
+# Commits that changed formatting and nothing else. Blame skips them:
+#
+#     git config blame.ignoreRevsFile .git-blame-ignore-revs
+#
+# GitHub reads this file automatically. Add a revision here only when the
+# commit is genuinely mechanical — a real change hidden in one becomes
+# invisible to everyone looking for it later.
+
+# Reformat with ruff
+6c12bdd5065fe49199c9e8316b24580bf4c828a7

foilstack-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: ci
+on: [push, pull_request]
+
+# Secret scanning is deliberately not here. CI runs after a push, and this
+# repository is public — a credential this found would already be scraped, and
+# the only remedy left would be rotation. The scan that can actually stop one
+# is the pre-commit hook, which runs before the commit exists. See
+# .pre-commit-config.yaml.
+
+jobs:
+  # Unlike the secret scan, these are worth running here: a contributor may not
+  # have pre-commit installed, and a lint failure found after the push costs
+  # nothing but a second commit.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run ruff check src tests scripts
+      - run: uv run ruff format --check src tests scripts
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+
+    # Postgres is not optional here. `tests/test_isolation.py` builds its own
+    # database and drives the real application against it; without a server it
+    # *skips*, and skipping is exactly what it must not do — those are the
+    # tests that prove one account cannot read, edit or delete another's cards.
+    # Run without this, the suite reported 65 passed / 30 skipped and called it
+    # green.
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: foilstack
+          # Named so it reads as disposable and so the repository's own
+          # gitleaks rule does not flag it — a literal password assignment is
+          # exactly what that rule is for, and it should keep firing on real
+          # ones rather than being allowlisted away for this file.
+          POSTGRES_PASSWORD: ci-placeholder
+          POSTGRES_DB: foilstack
+        ports: ["5434:5432"]
+        options: >-
+          --health-cmd "pg_isready -U foilstack -d foilstack"
+          --health-interval 10s --health-timeout 5s --health-retries 10
+
+    env:
+      FOILSTACK_TEST_DATABASE_URL: postgresql+psycopg://foilstack:ci-placeholder@localhost:5434/foilstack
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+
+      # One run, then two questions of it: did anything fail, and did anything
+      # *skip*. A skip is a test that did not run, and the ones that skip here
+      # are the account-isolation tests — a green tick that means "we did not
+      # check" is worse than a red one.
+      - name: tests
+        run: |
+          set -o pipefail
+          uv run pytest -q --no-header -rs 2>&1 | tee /tmp/pytest.out
+          if grep -qE '[0-9]+ skipped' /tmp/pytest.out; then
+            echo "::error::tests were skipped — see the SKIPPED lines above"
+            exit 1
+          fi

foilstack-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: release
+
+# Publishing is deliberately manual and tag-driven. A release on every push to
+# main would mean any merge burns a version number on PyPI, where versions
+# cannot be reused or deleted — only yanked.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+
+      # The wheel carries the templates, the static files and the migrations,
+      # none of which are Python and any of which can silently stop being
+      # included. Checked here rather than discovered by whoever pip-installs
+      # the release: a package that imports fine and 500s on its first page is
+      # worse than one that fails to build.
+      - name: the wheel has to contain more than Python
+        run: |
+          python - <<'PY'
+          import zipfile, glob, sys
+          whl = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(whl).namelist()
+          required = [
+              "foilstack/web/templates/base.html",
+              "foilstack/web/static/app.css",
+              "foilstack/migrations/env.py",
+          ]
+          missing = [r for r in required if r not in names]
+          versions = [n for n in names if "/migrations/versions/" in n and n.endswith(".py")]
+          if missing:
+              sys.exit(f"missing from {whl}: {missing}")
+          if not versions:
+              sys.exit(f"no migration revisions in {whl}")
+          print(f"{whl}: {len(names)} files, {len(versions)} migrations")
+          PY
+
+      # The tag is a claim about what is inside the wheel, and nothing else
+      # checks it. Hatchling reads the version from
+      # `src/foilstack/__init__.py`, so tagging v0.2.0 against a source that
+      # still says 0.1.21 publishes 0.1.21 — under a tag that says otherwise,
+      # to an index where that number can never be corrected.
+      - name: the tag has to match the version in the wheel
+        if: github.ref_type == 'tag'
+        run: |
+          python - <<'PY'
+          import glob, os, sys
+          built = os.path.basename(glob.glob("dist/*.whl")[0]).split("-")[1]
+          tagged = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if built != tagged:
+              sys.exit(f"tag says {tagged}, wheel says {built} — refusing to publish")
+          print(f"tag and wheel agree on {built}")
+          PY
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    # Trusted publishing: PyPI verifies this workflow's OIDC identity, so there
+    # is no API token to store, rotate or leak.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

foilstack-0.2.0/.gitignore

@@ -0,0 +1,240 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Your catalogue, scans and inventory. Local data, never committed — and the
+# vector index alone is hundreds of megabytes.
+/data/
+
+# Deployment-specific compose settings (container names, tunnel, GPU services).
+# Local to whichever host this runs on; never committed.
+docker-compose.override.yml
+
+# Database dumps written by the `backup` service. Never in git.
+backups/
+
+# Screenshots generated by scripts/preview.py. Regenerate them, do not commit
+# them — they are a build product of a throwaway database and go stale silently.
+# The one screenshot the README uses lives in docs/ and is committed on purpose.
+shots/
+
+# Demo build artifacts. The GIF and the WebP under the app's static directory
+# are committed — the landing page serves both, WebP first with the GIF as the
+# fallback, and the README shows the GIF. Playwright's webm is not: it is for
+# posting to places that take real video, and regenerating it is one command.
+src/foilstack/web/static/demo/video/

foilstack-0.2.0/.gitleaks.toml

@@ -0,0 +1,59 @@
+# Secret scanning config, used by the gitleaks pre-commit hook.
+#
+# Deliberately not run in CI: CI happens after the push, and this repo is
+# public, so a credential it found would already be scraped. Rotation would be
+# the only remedy left. The scan that can prevent a leak is the one that runs
+# before the commit exists.
+#
+# This file earns its place. Measured against gitleaks v8.30 with its default
+# ruleset and nothing else, a file containing POSTGRES_PASSWORD=<literal>,
+# HF_TOKEN=hf_<literal> and a Postgres URL with an inline password produced
+# "no leaks found". The defaults are tuned for cloud provider tokens; the
+# secrets this project actually holds are none of those.
+title = "foilstack"
+
+[extend]
+useDefault = true
+
+[[rules]]
+id = "foilstack-env-assignment"
+description = "A secret-shaped environment variable assigned a literal value"
+# No lookahead: gitleaks uses Go's RE2, which has none. Placeholders are
+# excluded by the allowlist below rather than by the pattern.
+regex = '''(?i)\b(CLOUDFLARE_TUNNEL_TOKEN|ADMIN_PASSWORD|POSTGRES_PASSWORD|HF_TOKEN|POSTHOG_API_KEY|TURNSTILE_SECRET_KEY|OPENAI_API_KEY|ANTHROPIC_API_KEY)\s*[:=]\s*['"]?[A-Za-z0-9_\-\.]{8,}'''
+tags = ["key", "env"]
+
+  [rules.allowlist]
+  regexTarget = "line"
+  regexes = [
+    '''\$\{''',            # ${VAR} indirection
+    '''(?i)your[-_]''',
+    '''(?i)changeme''',
+    '''(?i)placeholder''',
+    '''(?i)example''',
+    '''(?i)xxx+''',
+  ]
+
+[[rules]]
+id = "foilstack-connection-uri"
+description = "A connection string with the password written into it"
+# The shape of DATABASE_URL, which is the most sensitive value this project
+# holds and which neither the default ruleset nor the rule above catches: the
+# password sits between a colon and an at-sign rather than after an equals.
+regex = '''(?i)\b(postgres|postgresql|redis|amqp|mongodb|mysql)(\+[a-z]+)?://[^\s:/@]+:[^\s:/@]{6,}@'''
+tags = ["key", "uri"]
+
+  [rules.allowlist]
+  regexTarget = "line"
+  regexes = [
+    '''\$\{''',            # ${VAR} indirection, as in docker-compose
+    '''(?i)your[-_]''',
+    '''(?i)change[-_]?me''',
+    '''(?i)placeholder''',
+    '''(?i)example''',
+    '''(?i)localhost''',
+    '''(?i)\bfoilstack:foilstack\b''',   # the documented local default
+  ]
+
+[allowlist]
+paths = ['''\.env\.example$''', '''\.gitleaks\.toml$''']

foilstack-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,81 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=2048"]
+      # Overlaps with gitleaks and costs a line. A stray id_rsa or .pem is the
+      # one secret that arrives as a whole file rather than a value on a line,
+      # and a check aimed squarely at it is cheap insurance.
+      - id: detect-private-key
+      # Licences are shipped verbatim. The whitespace hooks are right about
+      # every other file and wrong about these: the OFL asks that the licence
+      # travel with the fonts, and quietly reformatting somebody else's licence
+      # text — even a trailing space — is not our edit to make.
+      - id: end-of-file-fixer
+        exclude: ^(LICENSE|.*/OFL\.txt)$
+      - id: trailing-whitespace
+        exclude: ^(LICENSE|.*/OFL\.txt)$
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.4
+    hooks:
+      # Lint first so a fix that changes layout is then formatted, rather than
+      # the two disagreeing across a commit.
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.3.1
+    hooks:
+      - id: mypy
+        # Runs against src/ only — the settings live in pyproject.toml so a
+        # local `uv run mypy` and the hook cannot disagree.
+        files: ^src/foilstack/
+        additional_dependencies:
+          - sqlalchemy[mypy]>=2.0
+          - pydantic>=2.7
+          - types-requests
+
+  # Bumps the patch version when application code is committed, so the footer
+  # and the User-Agent always name a build that is actually running. It stages
+  # its own edit; a hook that leaves the change unstaged makes every commit
+  # fail once and need repeating.
+  #
+  # `pass_filenames: false` because it decides for itself from the index which
+  # paths are staged, and `always_run: false` with a `files:` filter so a
+  # README or CI commit does not move the version — a number that moves for
+  # everything means nothing.
+  - repo: local
+    hooks:
+      - id: bump-version
+        name: bump the patch version
+        entry: python scripts/bump_version.py
+        # `language: python` rather than `system`: pre-commit provisions its own
+        # interpreter, so this works on a machine where `python` is not on PATH
+        # — which is this one, and is most Linux boxes. The script imports only
+        # the standard library, so the environment needs nothing installed.
+        language: python
+        files: ^src/foilstack/
+        pass_filenames: false
+
+  # The suite, on push rather than on commit. See scripts/check-tests.sh for
+  # why: a plain pytest hook is green on a machine with no Postgres, because
+  # the account-isolation tests skip rather than fail — and those are the ones
+  # worth gating on. Install it with:
+  #
+  #     pre-commit install --hook-type pre-push
+  - repo: local
+    hooks:
+      - id: tests
+        name: tests (and nothing skipped)
+        entry: scripts/check-tests.sh
+        language: script
+        stages: [pre-push]
+        pass_filenames: false
+        always_run: true