Runbook: sequence modernization, hardening, documentation, and UX work

[DenWin]

Purpose

Provide the execution order for turning this fork into a distinct, testable, secure, and maintainable project. This is the coordination runbook for #9, #16, #24, and #31; the linked implementation issues remain the source of detailed acceptance criteria.

Operating rules

1. Keep main releasable. One concern per pull request; use Closes #….
2. Apply TDD to new behavior. For legacy behavior, add characterization tests before refactoring it.
3. Every defect fix needs a regression test and, where practical, a representative real-world fixture.
4. Record test command, result, fixture provenance, resource usage, and known limitations in the pull request.
5. Do not add converters until capability modeling, process isolation, and the assessment matrix are trustworthy.
6. Update documentation and ADRs in the same change that alters behavior or architecture.
7. Stop promotion when security, data-loss, migration, or rollback evidence is missing.

Ordered execution

Phase 0 — stabilize ownership and triage

• Decide the new project identity in Decide and plan a distinct project identity #39. Select the name now; defer mechanical renaming until its migration plan is approved.
• Confirm PR Optimize Docker build layers #8 / closed issue Optimize Docker build stages and runtime layering #1 is merged or otherwise resolved before stacking Docker work.
• Freeze broad converter expansion while the baseline and security boundaries are established.
• Copy and address upstream Authenticated Local File Inclusion via LaTeX \input directive in xelatex converter C4illin/ConvertX#573 first: authenticated LaTeX local-file disclosure. Add an exploit regression test before containment. Do not wait for the complete architecture audit.

Exit gate: the known file-disclosure path is contained and tested; the project identity decision is recorded; main is green.

Phase 1 — create a trustworthy engineering baseline

Resolve in this order:

1. Audit existing behavior and testability before retrospective testing #17 — complete the code, behavior, dependency, and testability audit.
2. Create a characterization harness and testable application bootstrap #18 — introduce the testable bootstrap and characterization harness.
3. Establish TDD, retrospective characterization, and real-world assessment #16 — establish the TDD, retrospective-test, real-world-fixture, and assessment policy.
4. Harden GitHub Actions and CI/CD permissions #32 — establish least-privilege CI with required, reproducible checks.
5. Unify linting, type checking, formatting, and policy validation #38 — unify formatting, linting, type checking, schema validation, and policy checks.
6. Make application builds deterministic and independently verifiable #36 — make builds deterministic and independently verifiable.

Start #25 alongside this phase. Start #26 and #30 after the audit establishes evidence.

Exit gate: a clean checkout can run the documented checks; protected changes cannot bypass them; legacy seams have characterization coverage sufficient for the next phase.

Phase 2 — characterize and harden core behavior

Resolve characterization before broad refactoring:

1. Characterize authentication, authorization, and account lifecycle #19 — authentication and account lifecycle.
2. Characterize file storage, job lifecycle, and destructive operations #20 — storage, job lifecycle, cleanup, and destructive operations.
3. Characterize converter catalog, selection, orchestration, and concurrency #21 — converter catalog, selection, orchestration, and concurrency.
4. Strengthen converter adapter contracts and real-world fixture coverage #22 — adapter contracts and real-world fixture matrix.
5. Add browser-level characterization for existing user workflows #23 — browser-level characterization of existing workflows.

Then implement #33 and #34 in small, tested slices. During this phase copy and consolidate these upstream defects:

• Large file upload causes high memory usage and container crash C4illin/ConvertX#364 and Large files do not upload C4illin/ConvertX#64 — unbounded/in-memory uploads and conversion beginning before upload completion.
• clearJobs() spins forever on FUSE mounts when a leaked fd blocks rmSync, permanently disabling auto-delete C4illin/ConvertX#584 — cleanup can spin indefinitely and leak a file handle on FUSE-like storage.
• ffmpeg h264 conversion failure - Error: stderr maxBuffer length exceeded C4illin/ConvertX#565 — long FFmpeg jobs fail when captured process output exceeds the buffer.
• Converting a 2 page PDF to PNG, creates 2 png files, but they cannot be downloaded C4illin/ConvertX#541, Animated image conversion - Invalid link returned C4illin/ConvertX#340, and Multipage PDF's > JPEG only converts the first page C4illin/ConvertX#273 — multi-page/multi-output conversions do not map cleanly to one database result/download.
• SQLiteError when starting the image in Docker C4illin/ConvertX#350 — bind-volume ownership, non-root access, and SELinux compatibility.

Each copied issue should link its upstream source, state whether it was reproduced on this fork, and define a local regression test rather than assuming the upstream diagnosis is current.

Exit gate: bounded uploads and subprocesses, deterministic job transitions, reliable cleanup, modeled multi-output results, and tested recovery paths.

Phase 3 — harden container, build, and delivery

Resolve in dependency order:

1. Evaluate and pin the production Debian base image #2 — select and pin the production base using measured compatibility and security data.
2. Make downloaded Docker build dependencies reproducible #3 — pin and verify downloaded build dependencies.
3. Run the ConvertX container as a non-root user #4 — move runtime execution to a non-root user, including a documented volume migration.
4. Audit and reduce Docker runtime dependencies #5 — measure and reduce runtime dependencies and image size.
5. Improve container health checks and subprocess lifecycle handling #7 — add meaningful health checks and bounded subprocess lifecycle handling.
6. Add BuildKit caching and multi-platform Docker validation #6 — add BuildKit caching and multi-platform validation after the build is deterministic.
7. Harden Docker image and release supply chain #35 — complete provenance, SBOM, vulnerability scanning, signing/attestation, and release controls.
8. Harden repository governance and security configuration #37 — complete repository governance and security configuration.

Use #28 for deployment, backup, recovery, upgrade, and rollback procedures as the behavior stabilizes.

Exit gate: reproducible signed artifacts, non-root runtime, tested volume upgrade, useful health reporting, vulnerability policy, and a rehearsed rollback.

Phase 4 — redesign the user workflow

Implement #9 only after the underlying contracts are stable:

1. Support explicit local, OIDC, and built-in authentication modes #11 — durable, revocable sessions across container restarts.
2. Modernize the login screen #10 — modern accessible login UI.
3. Redesign the multi-file upload queue and file actions #12 — bounded multi-file upload queue and accessible icon actions.
4. Add capability-aware target and converter selection #13 — capability-aware conversion choices.
5. Add shared batch defaults and per-file conversion settings #14 — validated batch defaults and per-file settings.
6. Add safe output filename templates with live preview #15 — safe filename-template parser and preview.

Complete #29 with the stable HTTP and user workflows. Add load, browser, accessibility, and real-world conversion evidence for the release candidate.

Exit gate: the full workflow is covered at unit, integration, browser, and representative real-world levels; limits and failure modes are visible to users.

Phase 5 — selectively import upstream compatibility work

Reproduce before copying. Prefer adding the case to #22's assessment corpus first:

• [Bug] serveral tools converted faulty pdf after converting Chinese included markdown because no corresponding font was found C4illin/ConvertX#547 — CJK fonts missing in Markdown-to-PDF.
• HEIC conversion fails for iPhone 17 Pro Max photos with libheif security limit error C4illin/ConvertX#598 — iPhone HEIC/libvips security-limit failure; verify the bundled libvips version first.
• JPEG Portrait to PDF is always Landscape C4illin/ConvertX#590 — JPEG orientation lost in PDF output.
• Convert PDF to CSV error via LibreOffice C4illin/ConvertX#561 — invalid PDF-to-CSV capability; check whether upstream PR fix(libreoffice): fix CSV export crash and add LibreOffice Calc category C4illin/ConvertX#567 already resolves it locally.
• stderr: heifsave: Unsupported compression C4illin/ConvertX#555 — PNG-to-AVIF compression incompatibility.
• 通过docker-compose方式安装并启动服务测试，docx转换pdf文件报错，Failed, check logs C4illin/ConvertX#369 — DOCX-to-PDF adapter/runtime failures.
• Fails when converting mp3-m4b or m4a C4illin/ConvertX#315 — audio cover art incorrectly treated as video.

Upstream issues not to copy separately now

These are already represented locally; add upstream references or test cases to the existing issue instead:

• [Feature Request] Conversion settings C4illin/ConvertX#324 → Add shared batch defaults and per-file conversion settings #14 (conversion settings).
• [Feature Request] Filter for sensible convertion C4illin/ConvertX#238 and Feature Request: Option to define allowed conversions C4illin/ConvertX#173 → Add capability-aware target and converter selection #13 (capability-aware and policy-aware choices).
• Sample Guide for Programmatically Using ConvertX API C4illin/ConvertX#535 → Document HTTP interfaces and end-user conversion workflows #29 (HTTP/API documentation; public API support remains a product decision).
• Update README.md for adding a JWT_SECRET C4illin/ConvertX#502 and [Improvement] On HTTP connection, make it clear ConvertX won't work without the proper environment variable set. C4illin/ConvertX#205 → Support explicit local, OIDC, and built-in authentication modes #11 and Create deployment, operations, backup, recovery, and security runbooks #28 (session/configuration/deployment behavior).
• Feature: Message Invalid credentials C4illin/ConvertX#46 and Can't login C4illin/ConvertX#488 → Modernize the login screen #10 (login error and UX behavior).
• Feature: Allow choosing compression levels for formats that support them C4illin/ConvertX#39 → Add shared batch defaults and per-file conversion settings #14 (quality/compression settings).
• [Feature Request]how to cancel pending task? C4illin/ConvertX#330, [Feature Request] Make error logs visible from web ui C4illin/ConvertX#379, [Feature Request] Custom values for resource limits C4illin/ConvertX#403, and File conversion works fine but not videos for some reasons C4illin/ConvertX#554 → Harden application resilience, job state, and data integrity #34 (cancellation, diagnostics, resource controls, and job status).
• new release fails to create container. error stating out of space. C4illin/ConvertX#507 → Audit and reduce Docker runtime dependencies #5 and Harden Docker image and release supply chain #35 (image size and supply-chain footprint).

Defer converter requests and major identity-provider/authorization features until Phases 1–4 establish measurable safety and product scope.

Per-issue execution checklist

• Confirm dependencies and current reproduction.
• Define observable acceptance criteria and threat/failure cases.
• Add the failing test or characterization first.
• Implement the smallest safe change.
• Run unit, integration, browser, and applicable real-world tests.
• Record time, memory, disk, output correctness, and failure/recovery evidence where relevant.
• Update architecture, user, operator, and ADR documentation as applicable.
• Verify upgrade and rollback behavior.
• Link upstream issue/PR without implying upstream endorsement.

Review cadence

• Re-triage this runbook after each phase exit or newly disclosed security issue.
• Close copied upstream issues based on local acceptance criteria, not merely because upstream closes them.
• Review deferred upstream defects monthly against the real-world assessment matrix.
• Keep only the next phase actively in progress; later phases remain ordered backlog.