latextify 0.1.0rc1__tar.gz

latextify-0.1.0rc1/.dockerignore

@@ -0,0 +1,20 @@
+# Build context hygiene for deploy/render/Dockerfile (context = repo root).
+# Only the installable package + metadata should reach the image.
+.git
+.venv
+.claude
+__pycache__
+**/__pycache__
+*.pyc
+build
+dist
+output
+png
+plans
+tests
+examples
+deploy/hf-space/README.md
+deploy/hf-space/DEPLOY.md
+deploy/render/DEPLOY.md
+*.log
+uv.lock

latextify-0.1.0rc1/.gitattributes

@@ -0,0 +1,5 @@
+# Keep launcher line endings correct on every platform, regardless of
+# the contributor's core.autocrlf setting.
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.sh  text eol=lf

latextify-0.1.0rc1/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-deps:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

latextify-0.1.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,172 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv sync --locked
+      - name: Ruff
+        run: uv run ruff check .
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.11", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: uv sync --locked
+      - name: Unit tests (no TeX engine, no network)
+        run: uv run pytest -q -m "not tectonic and not network"
+
+  integration:
+    # Full suite including real Tectonic compiles. One platform is enough:
+    # the compile path is exercised on Windows by local development.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.12"
+      - name: Cache Tectonic binary and package bundle
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: |
+            ~/.cache/latextify
+            ~/.cache/Tectonic
+          key: tectonic-${{ runner.os }}-v1
+      - name: Install
+        run: uv sync --locked
+      - name: Pre-fetch Tectonic binary
+        # Test skip-guards only DETECT the binary at collection time (no
+        # download), so the integration job fetches it explicitly first. The
+        # download is a pinned, checksum-verified release-asset URL served by a
+        # CDN (not the rate-limited releases API), so no token is needed.
+        run: uv run python -c "from latextify.compile.tectonic import ensure_tectonic; print(ensure_tectonic())"
+      - name: Full test suite (real docx -> PDF compiles)
+        run: uv run pytest -q -m "not network"
+
+  offline-kit:
+    # Proves the whole offline story end to end: build a kit (network ON),
+    # then install it and compile a PDF with the network POISONED. This is the
+    # regression gate that keeps a stray runtime network call from silently
+    # breaking air-gapped use. Kept small (one Python, one journal) for speed;
+    # the release workflow builds the full multi-target kits.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.13"
+      - name: Cache Tectonic binary and package bundle
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: |
+            ~/.cache/latextify
+            ~/.cache/Tectonic
+          key: tectonic-${{ runner.os }}-v1
+      - name: Install
+        run: uv sync --locked
+      - name: Pre-fetch Tectonic (pinned, checksum-verified release asset)
+        run: uv run python -c "from latextify.compile.tectonic import ensure_tectonic; print(ensure_tectonic())"
+      - name: Build a current-platform kit (network ON) and a fixture manuscript
+        run: |
+          uv run latextify make-kit --target current --python-versions 3.13 \
+            --journals revtex4-2 -o build
+          uv run python - <<'PY'
+          from docx import Document
+          d = Document()
+          d.add_heading("Offline CI Demo", 0)
+          d.add_paragraph("Ada Offline")
+          d.add_heading("Abstract", 1)
+          d.add_paragraph("A fixture manuscript compiled with no network access.")
+          d.add_heading("Introduction", 1)
+          d.add_paragraph("Body text exercising headings, an abstract, and a PDF compile.")
+          d.save("demo.docx")
+          PY
+          echo "PYBIN=$(uv python find 3.13)" >> "$GITHUB_ENV"
+      - name: Install kit + convert to PDF with the network POISONED
+        env:
+          # GitHub de-dupes env keys case-insensitively, so set ONE case only.
+          # Uppercase is honoured by Rust/reqwest (Tectonic) and Python alike.
+          HTTPS_PROXY: http://127.0.0.1:9
+          HTTP_PROXY: http://127.0.0.1:9
+          ALL_PROXY: http://127.0.0.1:9
+        run: |
+          KIT=build/latextify-offline-linux-x64
+          "$PYBIN" "$KIT/install.py"
+          "$KIT/latextify" convert demo.docx -j revtex4-2 -o demo-out --pdf
+          test -f demo-out/revtex4-2/main.pdf || { echo "no PDF produced offline"; exit 1; }
+          echo "offline PDF compiled: $(du -h demo-out/revtex4-2/main.pdf)"
+
+  offline-kit-py310-windows:
+    name: offline kit installs on Python 3.10 (Windows)
+    # Every other kit-install gate above targets the newest supported
+    # interpreter (3.13) on Linux; none proves the offline kit against the
+    # OLDEST supported Python (3.10, our documented floor -- see
+    # requires-python in pyproject.toml) on the platform most kit users
+    # actually run: Windows. A future dependency bump could silently break
+    # the 3.10 floor without this catching it. Kept fast: emit-only
+    # (--no-warm-tex, no --pdf) -- the PDF/Tectonic offline path is already
+    # covered by the `offline-kit` job above.
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: uv sync --locked
+      - name: Set up the TARGET Python 3.10 (what install.py will run under)
+        id: py310
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.10"
+      - name: Build an emit-only kit covering Python 3.10 (network ON)
+        run: uv run latextify make-kit --target current --python-versions 3.10 --no-warm-tex --output build
+      - name: Install the kit under Python 3.10, network POISONED
+        env:
+          # Same reasoning as the Linux offline-kit job: uppercase only, one
+          # case, so GitHub's case-insensitive env-key de-dupe can't collide.
+          HTTPS_PROXY: http://127.0.0.1:9
+          HTTP_PROXY: http://127.0.0.1:9
+          ALL_PROXY: http://127.0.0.1:9
+        run: |
+          & "${{ steps.py310.outputs.python-path }}" "build/latextify-offline-windows-x64/install.py"
+          if ($LASTEXITCODE -ne 0) { throw "install.py failed under Python 3.10 (exit $LASTEXITCODE)" }
+      - name: Convert a fixture manuscript offline (emit-only, no --pdf)
+        env:
+          HTTPS_PROXY: http://127.0.0.1:9
+          HTTP_PROXY: http://127.0.0.1:9
+          ALL_PROXY: http://127.0.0.1:9
+        run: |
+          & "build/latextify-offline-windows-x64/LaTeXtify.bat" convert tests/fixtures/clean.docx -j revtex4-2 -o demo-out
+          if ($LASTEXITCODE -ne 0) { throw "convert failed under the Python 3.10 kit (exit $LASTEXITCODE)" }
+          if (-not (Test-Path "demo-out/revtex4-2/main.tex")) {
+            throw "Python 3.10 kit did not produce demo-out/revtex4-2/main.tex"
+          }
+          Write-Host "offline (Python 3.10, Windows): produced demo-out/revtex4-2/main.tex"

latextify-0.1.0rc1/.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "31 7 * * 1"
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4

latextify-0.1.0rc1/.github/workflows/dependency-audit.yml

@@ -0,0 +1,45 @@
+name: Dependency audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Weekly (Mon 06:00 UTC): catch advisories newly disclosed against pinned,
+    # otherwise-unchanged dependencies between code changes.
+    - cron: "0 6 * * 1"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  pip-audit:
+    name: pip-audit (locked runtime deps)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.12"
+      - name: Export locked runtime dependencies
+        # Audit exactly what ships to users: runtime deps only (no dev tools),
+        # resolved from uv.lock so the audit matches the pinned tree. --no-deps
+        # in the next step then audits precisely this closure without
+        # re-resolving. Hashes are omitted here because uv already verifies them
+        # on install; pip-audit's job in CI is CVE scanning, not integrity.
+        run: >-
+          uv export --frozen --no-dev --no-emit-project --no-hashes
+          --format requirements-txt -o requirements-audit.txt
+      - name: Audit for known vulnerabilities
+        # Exits non-zero if any dependency has a known advisory (PyPI + OSV).
+        #
+        # Failure policy: a PR that introduces or inherits a vulnerable
+        # dependency must upgrade it. An advisory may be waived only with a
+        # documented exception -- add `--ignore-vuln <ID>` below with a comment
+        # naming the package, advisory ID, why LaTeXtify is not exposed, and a
+        # review/expiry date.
+        run: uvx pip-audit --requirement requirements-audit.txt --no-deps

latextify-0.1.0rc1/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+# Publishes the sdist + wheel to PyPI. Triggers ONLY on a published GitHub
+# Release -- never on a plain push, a pull request, or even a tag push (tag
+# pushes drive release.yml's offline-kit build instead). This is the
+# machinery only: it cannot fire a real publish until an OWNER completes the
+# two one-time setup steps below.
+#
+# ---------------------------------------------------------------------------
+# OWNER SETUP REQUIRED before the first real publish (both are one-time,
+# human actions on pypi.org / GitHub -- this workflow cannot do either):
+#
+#   1. Register a PENDING trusted publisher at
+#      https://pypi.org/manage/account/publishing/ for a new project named
+#      "latextify":
+#        Owner:            pquarterman17
+#        Repository name:  LaTeXtify
+#        Workflow name:    publish.yml
+#        Environment name: pypi
+#      (PyPI creates the "latextify" project automatically on the first
+#      successful publish from this trusted publisher -- no manual project
+#      creation needed.)
+#
+#   2. Publish a GitHub Release (e.g. tag v0.1.0). The `release: published`
+#      event below is what triggers the `publish` job -- nothing publishes
+#      before that happens.
+# ---------------------------------------------------------------------------
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/latextify/
+    permissions:
+      id-token: write # OIDC trusted publishing -- no API token stored in secrets
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

latextify-0.1.0rc1/.github/workflows/release.yml

@@ -0,0 +1,120 @@
+name: Release kits
+
+# On a version tag, build the three offline kits and attach them (plus a
+# source zip and checksums) to a GitHub release, so an air-gapped machine can
+# "download from the releases page" with no online build host at all.
+# Complements the CI `offline-kit` job, which proves one kit installs and
+# compiles a PDF offline on every push.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write # create the release and upload assets
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build-kits:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.13"
+      - name: Cache Tectonic binary and package bundle
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: |
+            ~/.cache/latextify
+            ~/.cache/Tectonic
+          key: tectonic-${{ runner.os }}-v1
+      - name: Install
+        run: uv sync --locked
+      - name: Pre-fetch Tectonic (authenticated; anonymous API rate-limits on runners)
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: uv run python -c "from latextify.compile.tectonic import ensure_tectonic; print(ensure_tectonic())"
+
+      - name: Build native Linux kit (warms the shared, portable TeX cache)
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: uv run latextify make-kit --target linux-x64 -o build
+
+      # NOTE -- native-build preference: this workflow cross-builds the
+      # win-x64 (and macos-arm64) kits from a single Linux runner, on a
+      # GitHub-hosted-runner cost/simplicity tradeoff (one TeX warm-up pass
+      # instead of three, no matrix). A NATIVE Windows kit build --
+      # `latextify make-kit --target win-x64` run ON Windows, warming its own
+      # TeX cache directly -- is the PREFERRED way to produce the Windows
+      # kit: it exercises the real target-platform Tectonic binary end to
+      # end, rather than shipping `--no-warm-tex` and trusting that a
+      # Linux-warmed, source-only cache regenerates its engine format
+      # correctly the first time on Windows. (The CI `offline-kit-py310-windows`
+      # job partially covers this by installing+running a Windows kit, but it
+      # is also `--no-warm-tex`/emit-only for speed -- it does not warm-test
+      # this path either.) If a native Windows release runner ever becomes
+      # available, prefer switching the win-x64 build to it over this
+      # cross-build path.
+      - name: Build cross Windows/macOS kits, sharing the warmed cache
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          # The warmed cache ships TeX *sources* only (host-independent); the
+          # target regenerates its engine format offline. So warm ONCE on Linux
+          # and reuse it for the cross targets rather than re-downloading the
+          # whole TeX bundle two more times.
+          for tgt in win-x64 macos-arm64; do
+            uv run latextify make-kit --target "$tgt" --no-warm-tex -o build
+          done
+          uv run python - <<'PY'
+          import json
+          import shutil
+          from pathlib import Path
+
+          build = Path("build")
+          src_kit = build / "latextify-offline-linux-x64"
+          src_cache = src_kit / "tex-bundle-cache"
+          warmed = json.loads((src_kit / "bundle-info.json").read_text())["warmed_journals"]
+
+          for name in ("latextify-offline-windows-x64", "latextify-offline-macos-arm64"):
+              kit = build / name
+              shutil.copytree(src_cache, kit / "tex-bundle-cache", dirs_exist_ok=True)
+              info_path = kit / "bundle-info.json"
+              info = json.loads(info_path.read_text())
+              info["warm_tex"] = True
+              info["warmed_journals"] = warmed
+              info_path.write_text(json.dumps(info, indent=2) + "\n")
+              print(f"shared warmed cache into {name} ({len(warmed)} journals)")
+          PY
+
+      - name: Package kits, source zip, and checksums
+        run: |
+          git archive --format=zip --prefix=latextify-src/ -o build/latextify-source.zip HEAD
+          cd build
+          for d in latextify-offline-*/; do
+            name="${d%/}"
+            zip -qr "$name.zip" "$name"
+          done
+          sha256sum *.zip > SHA256SUMS.txt
+          echo "--- release assets ---"
+          ls -lh *.zip SHA256SUMS.txt
+          cat SHA256SUMS.txt
+
+      - name: Create release and upload assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          cd build
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "LaTeXtify ${GITHUB_REF_NAME}" \
+            --generate-notes \
+            latextify-offline-windows-x64.zip \
+            latextify-offline-linux-x64.zip \
+            latextify-offline-macos-arm64.zip \
+            latextify-source.zip \
+            SHA256SUMS.txt

latextify-0.1.0rc1/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Packaging output (uv build / python -m build)
+dist/
+
+# Secrets / local env (none tracked; ignore proactively)
+.env
+.env.*
+
+# Editors / IDEs (may embed local absolute paths)
+.vscode/
+.idea/
+
+# LaTeX build artifacts
+*.aux
+*.log
+*.bbl
+*.blg
+*.out
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+
+# Tool output trees (per-paper conversion output lives next to the paper, not here)
+output/
+
+# Launcher error log (startup.bat / startup.sh write this next to themselves)
+latextify-startup.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code files (never tracked in this public repo: local agent config,
+# session worktrees, and any project-instruction files stay local-only)
+.claude/
+CLAUDE.md
+CLAUDE.local.md
+
+# Local-only working notes (hosting/ops docs, parked roadmaps -- not for the
+# public repo; see the owner's notes/ directory)
+notes/
+
+# Offline kit build output (latextify make-kit)
+/build/

latextify-0.1.0rc1/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thanks for your interest! This is a young project; issues and PRs are welcome.
+
+## Development setup
+
+```
+git clone https://github.com/pquarterman17/LaTeXtify
+cd LaTeXtify
+uv sync          # creates .venv, installs everything incl. dev deps
+uv run pytest    # full suite (downloads the Tectonic binary on first run)
+uv run ruff check .
+```
+
+Fast subset (no TeX engine, no network):
+
+```
+uv run pytest -m "not tectonic and not network"
+```
+
+The `tectonic`-marked tests skip unless the Tectonic binary is already on
+PATH or in the cache — the skip guards deliberately never download at
+collection time. Fetch it once and they activate:
+
+```
+uv run python -c "from latextify.compile.tectonic import ensure_tectonic; print(ensure_tectonic())"
+```
+
+## Ground rules
+
+- **Tests first-class:** every bug fix carries a minimal reproducing test;
+  every feature carries tests. The suite must be green (`pytest` + `ruff
+  check .`) before a PR.
+- **Journals are data:** adding a journal means adding a folder under
+  `latextify/templates/journals/` (manifest.yaml + two Jinja templates +
+  golden-file tests) — never editing converter code. Copy `revtex4-2/` as
+  the worked example, and check vendored files' licenses before committing
+  them (see `sn-jnl/` and `iopart/` for the pattern; Wiley shows the
+  documented-skip pattern for non-redistributable classes).
+- **IR discipline:** data crossing stage boundaries uses the frozen
+  dataclasses in `latextify/model/` — no ad-hoc dicts.
+- **Commit style:** `type(scope): imperative description` (feat, fix,
+  refactor, docs, test, chore).
+- `.docx` test fixtures are generated, never hand-edited: each has a
+  committed `tests/fixtures/make_<name>.py` script.
+
+## Architecture orientation
+
+Read `plans/archive/LATEXTIFY_PLAN.md`'s Context section — it documents the
+pipeline, the write-once/`generated/` output contract, and the design
+decisions with dates.