feat!: Container infrastructure refactor (ADR-T-009)

.dockerignore → .containerignore

@@ -19,4 +19,6 @@
 /README.md
 /rustfmt.toml
 /storage/
-/target/
+/target/
+/adr/
+/docs/

.github/workflows/container.yaml

@@ -15,8 +15,90 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  lints:
+    name: Lints (Container infra)
+    runs-on: ubuntu-latest
+
+    steps:
+      - id: checkout
+        name: Checkout Repository
+        uses: actions/checkout@v6
+
+      # Phase 9 §9.1.3 — guard against re-introducing the
+      # `mailcatcher` dev sidecar (or any SMTP/mail config)
+      # into the production-shaped baseline. The override
+      # file is *expected* to mention `mailcatcher` and is
+      # deliberately excluded from the audit. Comments are
+      # stripped before grepping so the explanatory header
+      # in `compose.yaml` (which legitimately references
+      # `mailcatcher` in prose) does not trip the audit;
+      # we are looking for live YAML config, not docs.
+      - id: compose-baseline-no-mailcatcher
+        name: compose.yaml has no mailcatcher / SMTP wiring
+        run: |
+          set -eu
+          # awk strips `# ...` comments while preserving line
+          # numbering 1:1 with the source file, so any error
+          # output points the reader at the real line.
+          if awk '{ sub(/#.*/, ""); print }' compose.yaml \
+              | grep -nE 'mailcatcher|MAILER|SMTP|smtp_'; then
+            echo "::error file=compose.yaml::dev mail sidecar / SMTP config present in production-shaped baseline (ADR-T-009 §D1 / §8.1)"
+            exit 1
+          fi
+          echo "compose.yaml clean."
+
+      # Phase 9 / ADR-T-009 §D8 — vendored `su-exec.c` must not change
+      # without a fresh audit entry recording the new SHA-256
+      # in contrib/dev-tools/su-exec/AUDIT.md.
+      - id: su-exec-audit
+        name: su-exec audit log matches vendored source
+        run: |
+          set -eu
+          audit=contrib/dev-tools/su-exec/AUDIT.md
+          test -s "$audit"
+          recorded=$(sed -n '/^## Audit Log/,$ { s/^SHA-256: \([0-9a-f]\{64\}\)$/\1/p; }' "$audit" | tail -1)
+          actual=$(sha256sum contrib/dev-tools/su-exec/su-exec.c | cut -d' ' -f1)
+          if [ -z "$recorded" ]; then
+            echo "::error file=$audit::no SHA-256 entry found in '## Audit Log' section (ADR-T-009 §D8)"
+            exit 1
+          fi
+          if [ "$recorded" != "$actual" ]; then
+            echo "::error file=$audit::recorded SHA-256 ($recorded) does not match contrib/dev-tools/su-exec/su-exec.c ($actual). Append a new dated audit entry per ADR-T-009 §D8."
+            exit 1
+          fi
+          echo "su-exec audit current ($actual)."
+
+      # Phase 9 / ADR-T-009 Acceptance Criterion #7 — every env
+      # var listed in the entry script's manifest block must be
+      # documented in docs/containers.md.
+      - id: entry-env-docs
+        name: entry-script env vars documented
+        run: |
+          set -eu
+          script=share/container/entry_script_sh
+          vars=$(sed -n '/^# ENTRY_ENV_VARS:/,/^# END_ENTRY_ENV_VARS/p' "$script" \
+                  | grep -oE '[A-Z][A-Z0-9_]+' \
+                  | sort -u)
+          if [ -z "$vars" ]; then
+            echo "::error file=$script::ENTRY_ENV_VARS manifest block not found or empty (ADR-T-009 Acceptance Criterion #7)"
+            exit 1
+          fi
+          missing=0
+          for v in $vars; do
+            grep -q "$v" docs/containers.md || {
+              echo "::error file=docs/containers.md::env var '$v' is in the entry-script manifest but not documented"
+              missing=1
+            }
+          done
+          grep -q 'compose\.override\.yaml' docs/containers.md || {
+            echo "::error file=docs/containers.md::two-file Compose split (compose.override.yaml) is not documented"
+            missing=1
+          }
+          [ "$missing" -eq 0 ]
+
   test:
     name: Test (Docker)
+    needs: lints
     runs-on: ubuntu-latest
 
     strategy:

AGENTS.md

@@ -17,6 +17,10 @@ When working inside a package, prefer running only the `--package` tests,
 as the whole-project tests are slow to run. (Occasionally run the whole
 suite, for example when finishing up.)
 
+## Commit Messages
+
+When writing a commit message, be sure to review the last few commit message to compare the style.
+
 ## Running Tests
 
 When running tests, tee to a temp file (`/tmp/...`) and then grep that
@@ -45,6 +49,23 @@ API, perhaps using `#[doc(hidden)]` helpers when appropriate.
 
 Every test file (module) should maintain an index of the tests contained in the module-doc. The primary purpose is to make it easy to scan the test files to detect duplicates or overlapping coverage. Please opportunistically create if missing.
 
+## POSIX Paths
+
+Treat paths as opaque byte sequences. POSIX permits any byte except
+`\0` (NUL) and `/` (the path separator) in a file or directory name,
+and there is no guarantee that the bytes are valid UTF-8. Concretely:
+
+- Prefer `OsStr` / `OsString` / `Path` / `PathBuf` (or `Utf8Path`
+  when UTF-8 really is a precondition you intend to enforce) over
+  ad-hoc `String` handling.
+- Do not assume any particular character class — names may contain
+  spaces, newlines, control bytes, leading dashes, or arbitrary
+  non-UTF-8 bytes.
+- NUL termination is only required when crossing a libc/FFI
+  boundary (e.g. `CString` for `open(2)`); interior NUL bytes are
+  invalid for those APIs and must be rejected, not silently
+  truncated.
+
 ## Cross-Reference Conventions
 
 Eagerly corrected when spotted in **any** file!
@@ -59,6 +80,13 @@ use their own `ADR-<PREFIX>-<NNN>` form without the `§` prefix.
 | `T-`   | Torrust (root crate) | *(none yet)*                         |
 | `R-`   | render-text-as-image | `packages/render-text-as-image/`     |
 
+Helper crates (`index-health-check`, `index-auth-keypair`,
+`index-config`, `index-config-probe`, `index-cli-common`,
+`index-entry-script`) are internal implementation details of
+the root crate and do not own separate ADRs or specification
+docs. They share the `T-` prefix for any cross-references
+that target them.
+
 ### General Rules
 
 - Use `§§` for ranges: e.g. `§§IDEA M-12.2–12.5`.
@@ -76,5 +104,6 @@ use their own `ADR-<PREFIX>-<NNN>` form without the `§` prefix.
 To avoid partial or corrupted writes, always replace files atomically:
 
 1. Read the file.
-2. Using the CLI, `rm` the file.
-3. Recreate the file.
+2. Write the new content to a temporary file
+3. Rename the temporary file to atomically overwrite the original file:
+   `mv file.tmp file`