compile-pdf-rewrite 0.1.0__tar.gz

compile_pdf_rewrite-0.1.0/.coderabbit.yaml

@@ -0,0 +1,29 @@
+language: en-US
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: true
+  auto_review:
+    enabled: true
+    drafts: false
+  path_filters:
+    - "!dist/**"
+    - "!build/**"
+    - "!.next/**"
+    - "!node_modules/**"
+    - "!**/__pycache__/**"
+    - "!**/*.min.js"
+    - "!**/*.lock"
+    - "!**/package-lock.json"
+    - "!**/uv.lock"
+    - "!**/poetry.lock"
+  path_instructions:
+    - path: "**/*.{ts,tsx,js,jsx}"
+      instructions: "Flag unhandled promises, missing null checks, hardcoded secrets/env vars, and unsafe `any` usage. Skip stylistic preferences — Prettier handles those."
+    - path: "**/*.py"
+      instructions: "Flag unhandled exceptions, missing type hints on public functions, hardcoded secrets, and SQL injection risks. Skip style — Ruff handles those."
+chat:
+  auto_reply: true

compile_pdf_rewrite-0.1.0/.cursor/rules/baseline.mdc

@@ -0,0 +1,21 @@
+---
+description: PrintWithSynergy baseline rules
+alwaysApply: true
+---
+
+You are working in this repository, part of the printwithsynergy organization.
+
+# Conventions
+- Conventional commits (feat:, fix:, chore:, refactor:, docs:, test:)
+- Never commit secrets. Use .env (gitignored) for local config.
+- Prefer pure functions; isolate side effects.
+- Write tests alongside code changes when behavior changes.
+
+# Before modifying code
+- Use the code-review-graph MCP tools (get_impact_radius_tool, get_blast_radius) to check downstream impact.
+- For unfamiliar symbols, use sverklo_lookup or sverklo_refs first.
+- Never assume context. If the codebase has CLAUDE.md or AGENTS.md, read it first.
+
+# Style
+- Match existing code style. Do not reformat unrelated lines.
+- No "helper" refactors mixed with feature changes.

compile_pdf_rewrite-0.1.0/.cursorrules

@@ -0,0 +1,16 @@
+You are working in the `compile-pdf-rewrite` repository, part of the printwithsynergy organization.
+
+# Conventions
+- Conventional commits (feat:, fix:, chore:, refactor:, docs:, test:)
+- Never commit secrets. Use .env (gitignored) for local config.
+- Prefer pure functions; isolate side effects.
+- Write tests alongside code changes when behavior changes.
+
+# Before modifying code
+- Use the code-review-graph MCP tools (get_impact_radius_tool, get_blast_radius) to check downstream impact.
+- For unfamiliar symbols, use sverklo_lookup or sverklo_refs first.
+- Never assume context. If the codebase has CLAUDE.md or AGENTS.md, read it first.
+
+# Style
+- Match existing code style. Do not reformat unrelated lines.
+- No "helper" refactors mixed with feature changes.

compile_pdf_rewrite-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

compile_pdf_rewrite-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,39 @@
+name: publish-pypi
+
+# Publishes compile-pdf-rewrite to PyPI when a v*.*.* tag is pushed.
+#
+# Auth: PyPI API token stored in PYPI_TOKEN repository secret.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade pip build
+      - run: python -m build --sdist --wheel --outdir dist/
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}

compile_pdf_rewrite-0.1.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# compile-pdf-rewrite
+
+compile-pdf-rewrite
+
+## Code Review & Blast-Radius Protocol
+- Before edits: run code-review-graph impact tools on changed symbols
+- After edits: ensure tests pass before commit
+- CodeRabbit reviews PRs automatically; Cursor BugBot provides second opinion
+- Never disable the code-review-graph Launch Agent

compile_pdf_rewrite-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: compile-pdf-rewrite
+Version: 0.1.0
+Summary: CompilePDF rewrite producer.
+Project-URL: Homepage, https://compilepdf.com
+Project-URL: Repository, https://github.com/printwithsynergy/compile-pdf-rewrite
+Project-URL: Issues, https://github.com/printwithsynergy/compile-pdf-rewrite/issues
+Author-email: Print With Synergy <iam@quincy.codes>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: codex-pdf<2.0,>=1.15.0
+Requires-Dist: compile-pdf-core<1.0,>=0.1.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pikepdf>=8.13
+Requires-Dist: pillow>=10.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: structlog>=24.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# compile-pdf-rewrite
+
+Object-tree mutations for CompilePDF: OCG, metadata, colour-space, hygiene, lifecycle.
+
+Fifteen mutations across structural, hygiene, and lifecycle categories. OCG flips, page lifecycle ops, page-box patches, metadata set/strip, colour-space swap, JavaScript strip, PDF/X pin. Three-layer verifier: schema, determinism, nothing-else-touched.
+
+## Install
+
+```bash
+uv pip install compile-pdf-rewrite
+```
+
+## Position in the stack
+
+One of four [CompilePDF](https://compilepdf.com) producers (trap, impose, marks, rewrite). Each lives in its own repo and PyPI package so you install only what you need. Producers depend on `compile-pdf-core`, never on each other.
+
+- Repo: https://github.com/printwithsynergy/compile-pdf-rewrite
+- Deployment host: https://github.com/printwithsynergy/compile-pdf
+- License: AGPL-3.0-or-later

compile_pdf_rewrite-0.1.0/README.md

@@ -0,0 +1,19 @@
+# compile-pdf-rewrite
+
+Object-tree mutations for CompilePDF: OCG, metadata, colour-space, hygiene, lifecycle.
+
+Fifteen mutations across structural, hygiene, and lifecycle categories. OCG flips, page lifecycle ops, page-box patches, metadata set/strip, colour-space swap, JavaScript strip, PDF/X pin. Three-layer verifier: schema, determinism, nothing-else-touched.
+
+## Install
+
+```bash
+uv pip install compile-pdf-rewrite
+```
+
+## Position in the stack
+
+One of four [CompilePDF](https://compilepdf.com) producers (trap, impose, marks, rewrite). Each lives in its own repo and PyPI package so you install only what you need. Producers depend on `compile-pdf-core`, never on each other.
+
+- Repo: https://github.com/printwithsynergy/compile-pdf-rewrite
+- Deployment host: https://github.com/printwithsynergy/compile-pdf
+- License: AGPL-3.0-or-later

compile_pdf_rewrite-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "compile-pdf-rewrite"
+version = "0.1.0"
+description = "CompilePDF rewrite producer."
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+authors = [{ name = "Print With Synergy", email = "iam@quincy.codes" }]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+  "compile-pdf-core>=0.1.0,<1.0",
+  "codex-pdf>=1.15.0,<2.0",
+  "fastapi>=0.110",
+  "pikepdf>=8.13",
+  "pydantic>=2.6",
+  "click>=8.1",
+  "structlog>=24.1",
+  "Pillow>=10.2",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=4.1",
+  "ruff>=0.4",
+  "mypy>=1.9",
+]
+
+[project.scripts]
+compile-pdf-rewrite = "compile_pdf_rewrite.cli:main"
+
+[project.urls]
+Homepage = "https://compilepdf.com"
+Repository = "https://github.com/printwithsynergy/compile-pdf-rewrite"
+Issues = "https://github.com/printwithsynergy/compile-pdf-rewrite/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/compile_pdf_rewrite"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "C4", "RET"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src/compile_pdf_rewrite"]
+branch = true

compile_pdf_rewrite-0.1.0/src/compile_pdf_rewrite/__init__.py

@@ -0,0 +1,28 @@
+"""Rewrite producer — single-PDF-in/out object-tree mutations.
+
+Per spec §2.1 — 15 in-scope mutations across structural / hygiene /
+lifecycle / page-level categories. **No content-stream surgery** (font
+subsetting, image recompression, color reflow are out of scope and
+gated by a STOP-gate).
+
+Module structure (lands in Phase 1.x):
+
+- ``compile_pdf.rewrite.engine`` — pikepdf-driven mutator
+- ``compile_pdf.rewrite.plan_schema`` — JSON Schema validator
+- ``compile_pdf.rewrite.verify`` — three-layer post-condition checks (§2.3)
+- ``compile_pdf.rewrite.api`` — ``router`` exposing /v1/rewrite/apply
+- ``compile_pdf.rewrite.cli`` — ``register(group)`` for the top-level CLI
+
+Codex surface consumed (read-only context for plan validation):
+
+- :class:`codex_pdf.CodexDocument` — the document model rewrite plans
+  reference for page-index / OCG / metadata addressing.
+"""
+
+from __future__ import annotations
+
+from codex_pdf import CodexDocument
+
+from compile_pdf_core.version import REWRITE_SCHEMA_VERSION
+
+__all__ = ["CodexDocument", "REWRITE_SCHEMA_VERSION"]

compile_pdf_rewrite-0.1.0/src/compile_pdf_rewrite/api.py

@@ -0,0 +1,168 @@
+"""FastAPI router for the rewrite producer.
+
+Mounts under ``/v1/rewrite`` from :mod:`compile_pdf.api.main`. Single
+endpoint today: ``POST /v1/rewrite/apply``.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+import structlog
+from fastapi import APIRouter, HTTPException, Request, status
+from pydantic import BaseModel, Field
+
+from compile_pdf_core.cache import compute_cache_key, hash_canonical_plan
+from compile_pdf_core.retention import (
+    parse_consent,
+    persist_if_opted_in,
+    resolve_tenant,
+)
+from compile_pdf_rewrite.engine import RewritePlanError, apply_plan
+from compile_pdf_rewrite.plan_schema import RewritePlan
+from compile_pdf_rewrite.verify import verify_rewrite
+from compile_pdf_core.version import (
+    CODEX_DOCUMENT_SCHEMA_VERSION_PIN,
+    REWRITE_SCHEMA_VERSION,
+    VERSION,
+)
+
+logger = structlog.get_logger(__name__)
+
+router = APIRouter()
+
+
+class RewriteApplyRequest(BaseModel):
+    """Request envelope: an inline base64-encoded PDF + a plan.
+
+    Bytes-in / bytes-out. Lineage records persist to the configured S3
+    bucket asynchronously and are addressable by the returned
+    ``cache_key`` (Phase 5 lights up the actual store).
+    """
+
+    model_config = {"extra": "forbid"}
+
+    input_pdf_b64: str = Field(min_length=1)
+    plan: RewritePlan
+
+
+class RewriteApplyResponse(BaseModel):
+    """Response envelope. Output bytes are returned base64 so the
+    transport stays JSON; bypassed by the streaming variant in Phase 1.x."""
+
+    model_config = {"extra": "forbid"}
+
+    output_pdf_b64: str
+    pdf_sha256: str
+    input_sha256: str
+    plan_sha256: str
+    cache_key: str
+    cache_hit: bool = False
+    ops_applied: int
+    schema_version: str = REWRITE_SCHEMA_VERSION
+    compile_version: str = VERSION
+
+
+@router.post("/apply", response_model=RewriteApplyResponse, status_code=status.HTTP_200_OK)
+async def rewrite_apply(payload: RewriteApplyRequest, request: Request) -> RewriteApplyResponse:
+    """Apply a rewrite plan to an inline base64-encoded PDF.
+
+    Verification (spec §2.3 — three layers) runs server-side before the
+    response is returned. A failed verify is a 500 — the plan was valid
+    but the engine produced output that doesn't satisfy the post-conditions.
+    """
+    try:
+        input_bytes = base64.b64decode(payload.input_pdf_b64, validate=True)
+    except (ValueError, TypeError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"input_pdf_b64 is not valid base64: {exc}",
+        ) from exc
+
+    if not input_bytes:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="input is empty")
+
+    input_sha256 = hashlib.sha256(input_bytes).hexdigest()
+    plan_sha256 = hash_canonical_plan(payload.plan.model_dump(mode="json"))
+
+    try:
+        from codex_pdf.color import COLOR_SCHEMA_VERSION
+        from codex_pdf.geom import GEOM_SCHEMA_VERSION
+    except ImportError as exc:  # pragma: no cover — codex-pdf is a hard dep
+        raise HTTPException(
+            status_code=500, detail=f"codex-pdf surface unavailable: {exc}"
+        ) from exc
+
+    cache_key = compute_cache_key(
+        producer="rewrite",
+        input_sha256=input_sha256,
+        canonical_plan_sha256=plan_sha256,
+        codex_pdf_package_version=_resolve_codex_pdf_version(),
+        color_schema_version=COLOR_SCHEMA_VERSION,
+        geom_schema_version=GEOM_SCHEMA_VERSION,
+        codex_document_schema_version=CODEX_DOCUMENT_SCHEMA_VERSION_PIN,
+    )
+
+    logger.info(
+        "rewrite.apply.start",
+        ops=len(payload.plan.ops),
+        input_sha256=input_sha256[:16],
+        plan_sha256=plan_sha256[:16],
+        cache_key=cache_key[:16],
+    )
+
+    try:
+        result = apply_plan(input_bytes, payload.plan)
+    except RewritePlanError as exc:
+        raise HTTPException(status_code=422, detail=f"plan rejected: {exc}") from exc
+
+    verify = verify_rewrite(
+        input_bytes=input_bytes,
+        output_bytes=result.output_bytes,
+        plan=payload.plan,
+        determinism_replay=False,
+    )
+    if not (verify.layer1_schema and verify.layer3_unchanged):
+        logger.error("rewrite.apply.verify_failed", failures=verify.failures)
+        raise HTTPException(
+            status_code=500,
+            detail={"error": "verify failed", "failures": verify.failures},
+        )
+
+    consent = parse_consent(request)
+    response = RewriteApplyResponse(
+        output_pdf_b64=base64.b64encode(result.output_bytes).decode("ascii"),
+        pdf_sha256=result.pdf_sha256,
+        input_sha256=input_sha256,
+        plan_sha256=plan_sha256,
+        cache_key=cache_key,
+        cache_hit=False,
+        ops_applied=result.ops_applied,
+    )
+    retained = persist_if_opted_in(
+        consent=consent,
+        producer="rewrite",
+        tenant=resolve_tenant(request),
+        input_bytes=input_bytes,
+        output_bytes=result.output_bytes,
+        result=response.model_dump(mode="json"),
+        input_sha256=input_sha256,
+    )
+    logger.info(
+        "rewrite.apply.ok",
+        output_sha256=result.pdf_sha256[:16],
+        ops_applied=result.ops_applied,
+        consent=consent,
+        retained=retained,
+    )
+    return response
+
+
+def _resolve_codex_pdf_version() -> str:
+    """Read codex_pdf wheel version Compile was deployed against."""
+    try:
+        from codex_pdf import __version__ as codex_version
+    except ImportError:
+        return "unknown"
+    return str(codex_version)

compile_pdf_rewrite-0.1.0/src/compile_pdf_rewrite/cli.py

@@ -0,0 +1,91 @@
+"""Click subcommand registration for ``compile-pdf rewrite``.
+
+Local mode reads the input + plan from disk and runs the engine in-process.
+HTTP mode (``COMPILE_API_BASE`` set) is wired in Phase 1.x once the
+sidecar deploy lights up.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from compile_pdf_rewrite.engine import RewritePlanError, apply_plan
+from compile_pdf_rewrite.plan_schema import RewritePlan, rewrite_plan_json_schema
+from compile_pdf_rewrite.verify import verify_rewrite
+
+
+def register(group: click.Group) -> None:
+    """Attach the ``rewrite`` subcommand to the top-level CLI group."""
+
+    @group.command("rewrite", help="Apply a rewrite plan to a PDF.")
+    @click.option(
+        "--plan",
+        "plan_path",
+        type=click.Path(exists=True, dir_okay=False, path_type=Path),
+        required=True,
+        help="JSON rewrite-plan document.",
+    )
+    @click.option(
+        "--verify/--no-verify",
+        default=True,
+        help="Run three-layer post-condition checks (spec §2.3) before writing output.",
+    )
+    @click.argument(
+        "input_path",
+        type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    )
+    @click.argument(
+        "output_path",
+        type=click.Path(dir_okay=False, path_type=Path),
+    )
+    def rewrite_cmd(
+        plan_path: Path,
+        input_path: Path,
+        output_path: Path,
+        verify: bool,
+    ) -> None:
+        plan_dict = json.loads(plan_path.read_text(encoding="utf-8"))
+        try:
+            plan = RewritePlan.model_validate(plan_dict)
+        except Exception as exc:
+            click.echo(f"plan validation failed: {exc}", err=True)
+            sys.exit(3)
+
+        input_bytes = input_path.read_bytes()
+        try:
+            result = apply_plan(input_bytes, plan)
+        except RewritePlanError as exc:
+            click.echo(f"plan rejected: {exc}", err=True)
+            sys.exit(4)
+
+        if verify:
+            check = verify_rewrite(
+                input_bytes=input_bytes,
+                output_bytes=result.output_bytes,
+                plan=plan,
+            )
+            if not check.passed:
+                click.echo("verify failed:", err=True)
+                for failure in check.failures:
+                    click.echo(f"  - {failure}", err=True)
+                sys.exit(4)
+
+        output_path.write_bytes(result.output_bytes)
+        click.echo(
+            json.dumps(
+                {
+                    "ops_applied": result.ops_applied,
+                    "pdf_sha256": result.pdf_sha256,
+                    "output": str(output_path),
+                },
+                indent=2,
+            )
+        )
+
+    @group.command("rewrite-schema", hidden=True, help="Dump the rewrite-plan JSON Schema.")
+    def rewrite_schema_cmd() -> None:
+        click.echo(json.dumps(rewrite_plan_json_schema(), indent=2))